Added General Guidelines and fix link issues

docs/0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host.md

@@ -20,7 +20,7 @@ development image.
 The [supported images](https://download.automotivelinux.org/AGL/snapshots/master/latest/) exist for several boards as
 well as for the Quick EMUlator (QEMU).
 See the
-"[Quickstart](../1_Quickstart/Quickstart.md)"
+"[Quickstart](../1_Quickstart/Using_Ready_Made_Images.md)"
 section for more information on the ready-made images.
 
 1. **Use a Supported Linux Distribution:** To use the AGL software, it is
@@ -31,16 +31,6 @@ section for more information on the ready-made images.
    Basically, you should be running a recent version of Ubuntu, Fedora, openSUSE,
    CentOS, or Debian.
 
-   If you must use a build host that is not a native Linux machine, you can
-   install and use Docker to create a container that allows you to work as
-   if you are using a Linux-based host.
-   The container contains the same development environment (i.e. distros, packages,
-   and so forth) as would a properly prepared build host running a supported
-   Linux distribution.
-   For information on how to install and set up this Docker container, see the
-   "[Setting Up a Docker Container -- FIX ME](./docker-container-setup.html)"
-   section.
-
 2. **Be Sure Your Build Host Has Enough Free Disk Space:**
    Your build host should have at least 100 Gbytes.
 

docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md

@@ -31,7 +31,7 @@ follow the equivalent steps on your OS.
 First, create an SSH key pair with the command:
 
  ```sh
- ssh-keygen -t rsa -C "John Doe john.doe@example.com"
+ $ ssh-keygen -t rsa -C "John Doe john.doe@example.com"
  ```
 
 **Note:** This will ask you for a password to protect the private key as it generates a unique key. Please keep this password private, and DO NOT enter a blank password.
@@ -42,7 +42,7 @@ The generated SSH key pair can be found in the files ``~/.ssh/id_rsa`` and
 Next, add the private key in the ``id_rsa`` file to your key ring, e.g.:
 
  ```sh
- ssh-add ~/.ssh/id_rsa
+ $ ssh-add ~/.ssh/id_rsa
  ```
 
 Finally, add the public key of the generated key pair to the Gerrit server, with the following steps:

docs/5_How_To_Contribute/3_Working_with_Gerrit.md

@@ -53,7 +53,6 @@ Add the following section to ``.git/config``, and replace ``LFID``
 with your gerrit id.
 
 ```sh
-
 [remote "gerrit"]
    url = ssh://LFID@gerrit.automotivelinux.org:29418/AGL/documentation.git
    fetch = +refs/heads/*:refs/remotes/gerrit/*

docs/5_How_To_Contribute/4_Submitting_Changes.md

@@ -37,11 +37,12 @@ commit file is illustrated below in detail:
 
 ```sh
 
-[FAB-XXXX] A short description of your change with no period at the end
+A short description of your change with no period at the end
 
 You can add more details here in several paragraphs, but please keep each line
 width less than 80 characters. A bug fix should include the issue number.
 
+Bug-AGL: [SPEC-<JIRA-ID>]
 Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1
 Signed-off-by: Your Name <commit-sender@email.address>
 ```

docs/5_How_To_Contribute/5_Reviewing_Changes.md

@@ -35,11 +35,11 @@ title: Reviewing Changes
    or to return to the main change screen. Click on the yellow sticky
    pad to add comments to the whole file.
 
-   The focus of the page is on the comparison window. The changes made are
-   presented in green on the right versus the base version on the left.
-   Double click to highlight the text within the actual change to provide
-   feedback on a specific section of the code. Press *c* once the code is
-   highlighted to add comments to that section.
+      The focus of the page is on the comparison window. The changes made are
+      presented in green on the right versus the base version on the left.
+      Double click to highlight the text within the actual change to provide
+      feedback on a specific section of the code. Press *c* once the code is
+      highlighted to add comments to that section.
 
 5. After adding the comment, it is saved as a *Draft*.
 

docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md

@@ -54,8 +54,7 @@ Gerrit. Be mindful of what information you are publishing.
    at least *New Changes, New Patch Sets, All Comments* and *Submitted
    Changes*.
 
-Always track the projects you are working on; also see the
-feedback/comments mailing list to learn and help others ramp up.
+Always track the projects you are working on; also see the feedback/comments [mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn and help others ramp up.
 
 ## Topic branches
 
@@ -110,7 +109,7 @@ the history.
       the last commit on the list. Use the following command as an example:
 
       ```sh
-         git rebase -i HEAD~#Commits
+      $ git rebase -i HEAD~#Commits
       ```
 
       Be careful to uncomment the commit before moving it. ``#Commits`` is the
@@ -122,7 +121,7 @@ the history.
 $ ssh -p 29418 LFID@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u
 ```
 
--  [gerrit.automotivelinux.org](https://gerrit.hyperledger.org) is the current URL where the project is hosted.
+-  [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the current URL where the project is hosted.
 -  *status* : Indicates the topic's current status: open , merged,
    abandoned, draft, merge conflict.
 -  *project* : Refers to the current name of the project, in this case
@@ -145,21 +144,21 @@ To check out a specific change using Git, the following command usually
 works:
 
 ```sh
-git review -d CHANGEID
+$ git review -d CHANGEID
 ```
 
 If you don't have Git-review installed, the following commands will do
 the same thing:
 
 ```sh
-git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD
+$ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD
 ```
 
 For example, for the 4th version of change 2464, NN is the first two
 digits (24):
 
 ```sh
-git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD
+$ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD
 ```
 
 ## Using Draft Branches
@@ -171,14 +170,14 @@ publishing your change. The Draft Branches are pushed to
 The next command ensures a local branch is created:
 
 ```sh
-git checkout -b BRANCHNAME
+$ git checkout -b BRANCHNAME
 ```
 
 The next command pushes your change to the drafts branch under
 **TopicName**:
 
 ```sh
-git push REMOTE HEAD:refs/drafts/master/TopicName
+$ git push REMOTE HEAD:refs/drafts/master/TopicName
 ```
 
 ## Using Sandbox Branches
@@ -188,10 +187,10 @@ pushed to the ``refs/sandbox/USERNAME/BRANCHNAME`` location.
 
 These commands ensure the branch is created in Gerrit's server.
 
-::
-
-    git checkout -b sandbox/USERNAME/BRANCHNAME
-    git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME
+```sh
+$ git checkout -b sandbox/USERNAME/BRANCHNAME
+$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME
+```
 
 Usually, the process to create content is:
 
@@ -204,13 +203,13 @@ Usually, the process to create content is:
 The next command pushes forcibly without review:
 
 ```sh
-git push REMOTE sandbox/USERNAME/BRANCHNAME
+$ git push REMOTE sandbox/USERNAME/BRANCHNAME
 ```
 
 You can also push forcibly with review:
 
 ```sh
-git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME
+$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME
 ```
 
 ## Updating the Version of a Change
@@ -225,13 +224,13 @@ branch:
 
 ```sh
 
-git log REMOTE/master..master
+$ git log REMOTE/master..master
 
-c0
-...
-c7
+  c0
+  ...
+  c7
 
-git push REMOTE HEAD:refs/for/master/SOMETOPIC
+$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
 ```
 
 After you get reviewers' feedback, there are changes in **c3** and
@@ -240,7 +239,7 @@ changes the commit Ids, see the [rebasing](http://git-scm.com/book/en/v2/Git-Bra
 and push the changes again:
 
 ```sh
-git push REMOTE HEAD:refs/for/master/SOMETOPIC
+$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
 ```
 
 This new push creates a patches revision, your local history is then
@@ -270,24 +269,24 @@ For example, your ``REMOTE/master`` has the list of commits from **a0**
 to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus:
 
 ```sh
-git log --oneline REMOTE/master..master
+$ git log --oneline REMOTE/master..master
 
-a0
-a1
-a2
-a3
-a4
-c0
-c1
-...
-c7
+  a0
+  a1
+  a2
+  a3
+  a4
+  c0
+  c1
+  ...
+  c7
 ```
 
 If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull
 with a rebase as follows:
 
 ```sh
-    git pull --rebase REMOTE master
+$ git pull --rebase REMOTE master
 ```
 
 This pulls **a5-a7** and re-apply **c0-c7** on top of them:
@@ -309,20 +308,20 @@ Use these commands to change the configuration of Git in order to
 produce better logs:
 
 ```sh
-git config log.abbrevCommit true
+$ git config log.abbrevCommit true
 ```
 
 The command above sets the log to abbreviate the commits' hash.
 
 ```sh
-git config log.abbrev 5
+$ git config log.abbrev 5
 ```
 
 The command above sets the abbreviation length to the last 5 characters
 of the hash.
 
 ```sh
-git config format.pretty oneline
+$ git config format.pretty oneline
 ```
 
 The command above avoids the insertion of an unnecessary line before the

docs/5_How_To_Contribute/7_General_Guidelines.md

@@ -0,0 +1,114 @@
+---
+title: General Guidelines
+---
+
+## Getting help
+
+If you are looking for something to work on, or need some expert assistance in debugging a problem or working out a fix to an issue, our community is always eager to help. We hang out on various [developer meetings](https://www.automotivelinux.org/developer-meetings/) , IRC
+(#automotive on freenode.net) and the [mailing lists](https://lists.automotivelinux.org/g/agl-dev-community). We will be glad to help. The only silly question is the one you don't ask. Questions are in fact a great way to help improve the project as they highlight where our documentation could be clearer.
+
+## Reporting bugs
+
+If you are a user and you have found a bug, please submit an issue using [JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA issue, please try to search the existing items to be sure no one else has previously reported it. If it has been previously reported, then you might add a comment that you also are interested in seeing the defect fixed.
+
+If it has not been previously reported, create a new JIRA. Please try to provide sufficient information for someone else to reproduce the issue. One of the project's maintainers should respond to your issue within 24 hours. If not, please bump the issue with a comment and request that it be reviewed. 
+
+## Submitting your fix
+
+If you just submitted a JIRA for a bug you've discovered, and would like to
+provide a fix, we would welcome that gladly! Please assign the JIRA issue to
+yourself, then you can submit a change request (CR).
+
+**NOTE:** If you need help with submitting your first CR, we have created a brief [tutorial](./4_Submitting_Changes.md) for you.
+
+## Fixing issues and working stories
+
+Review the [open issue list](https://jira.automotivelinux.org/issues/?filter=-5) and find
+something that interests you. It is wise to start with something relatively straight forward and achievable, and that no one is already assigned. If no one is assigned, then assign the issue to yourself. Please be considerate and rescind the assignment if you cannot finish in a reasonable time, or add a comment saying that you are still actively working the issue if you need a little more time.
+
+## Reviewing submitted Change Requests (CRs)
+
+Another way to contribute and learn about Automotive Grade Linux is to help the
+maintainers with the review of the CRs that are open. Indeed
+maintainers have the difficult role of having to review all the CRs
+that are being submitted and evaluate whether they should be merged or
+not. You can review the code and/or documentation changes, test the
+changes, and tell the submitters and maintainers what you think. Once
+your review and/or test is complete just reply to the CR with your
+findings, by adding comments and/or voting. A comment saying something
+like "I tried it on system X and it works" or possibly "I got an error
+on system X: xxx " will help the maintainers in their evaluation. As a
+result, maintainers will be able to process CRs faster and everybody
+will gain from it.
+
+Just browse through the [open CRs on Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started.
+
+## Making Feature/Enhancement Proposals
+
+Review [JIRA](https://jira.automotivelinux.org/) to be sure that there isn't already an open (or recently closed) proposal for the same function. If there isn't, to make a proposal we recommend that you open a JIRA Epic, Story or Improvement, whichever seems to best fit the circumstance and link or inline a "one pager" of the proposal that states what the feature would do and, if possible, how it might be implemented. It would help also to make a case for why the feature should be added, such as identifying specific use case(s) for which the feature is needed and a case for what the benefit would be should the feature be implemented. Once the JIRA issue is created, and the "one pager" either attached, inlined in the description field, or a link to a publicly accessible document is added to the description, send an introductory email to the [agl-dev community](mailto:agl-dev-community@lists.automotivelinux.org) mailing list linking the JIRA issue, and soliciting feedback.
+
+Discussion of the proposed feature should be conducted in the JIRA issue itself, so that we have a consistent pattern within our community as to where to find design discussion.
+
+Getting the support of three or more of the AGL maintainers for the new feature will greatly enhance the probability that the feature's related CRs will be merged.
+
+## What makes a good change request?
+
+-  One change at a time. Not five, not three, not ten. One and only one.
+   Why? Because it limits the blast area of the change. If we have a
+   regression, it is much easier to identify the culprit commit than if
+   we have some composite change that impacts more of the code.
+
+-  Include a link to the JIRA story for the change. Why? Because a) we
+   want to track our velocity to better judge what we think we can
+   deliver and when and b) because we can justify the change more
+   effectively. In many cases, there should be some discussion around a
+   proposed change and we want to link back to that from the change
+   itself.
+
+-  Include unit and integration tests (or changes to existing tests)
+   with every change. This does not mean just happy path testing,
+   either. It also means negative testing of any defensive code that it
+   correctly catches input errors. When you write code, you are
+   responsible to test it and provide the tests that demonstrate that
+   your change does what it claims. Why? Because without this we have no
+   clue whether our current code base actually works.
+
+-  Minimize the lines of code per CR. Why? If you send a 1,000 or 2,000 LOC change, how long do you think it takes to review all of that code? Keep your changes to < 200-300 LOC, if possible. If you have a larger change, decompose it into multiple independent changess. If you are adding a bunch of new functions to fulfill the requirements of a new capability, add them separately with their tests, and then write the code that uses them to deliver the capability. Of course, there are always exceptions. If you add a small change and then add 300 LOC of tests, you will be forgiven;-) If you need to make a change that has broad impact or a bunch of generated code (protobufs, etc.). Again, there can be exceptions.
+
+      **NOTE:** Large change requests, e.g. those with more than 300 LOC are more likely than not going to receive a -2, and you'll be asked to refactor the change to conform with this guidance.
+
+-  Do not stack change requests (e.g. submit a CR from the same local branch
+   as your previous CR) unless they are related. This will minimize merge
+   conflicts and allow changes to be merged more quickly. If you stack requests
+   your subsequent requests may be held up because of review comments in the
+   preceding requests.
+
+-  Write a meaningful commit message. Include a meaningful 50 (or less)
+   character title, followed by a blank line, followed by a more
+   comprehensive description of the change. Each change MUST include the JIRA
+   identifier corresponding to the change (e.g. [SPEC-1234]). This can be
+   in the title but should also be in the body of the commit message. See the [complete requirements](./4_Submitting_Changes.md) for an acceptable change
+   request.
+
+   **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item.
+
+   ```sh
+   Bug-AGL: [SPEC-<JIRA-ID>] ....
+
+   Fix [SPEC-<JIRA-ID>] ....
+   ```
+
+Finally, be responsive. Don't let a change request fester with review comments such that it gets to a point that it requires a rebase. It only further delays getting it merged and adds more work for you - to remediate the merge conflicts.
+
+## Legal stuff
+
+We have tried to make it as easy as possible to make contributions. This applies to how we handle the legal aspects of contribution. 
+
+We simply ask that when submitting a patch for review, the developer must include a sign-off statement in the commit message.
+
+```sh
+Signed-off-by: John Doe <john.doe@example.com>
+```
+
+You can include this automatically when you commit a change to your
+local git repository using ``git commit -s``.