Added Contribution Guide 73/25473/8
authorShankho Boron Ghosh <shankhoghosh123@gmail.com>
Thu, 22 Oct 2020 18:40:00 +0000 (00:10 +0530)
committerJan-Simon Moeller <jsmoeller@linuxfoundation.org>
Fri, 23 Oct 2020 10:17:47 +0000 (10:17 +0000)
Exhaustive Contribution Guide. Removed Trailing Whitespaces.
Updated index.md. Abandoned accidental commits 25474,
25474 and uploading a new patchset. Corrected code renderings.

v2 (jsmoeller): Update contribution subchapters

Bug-AGL: SPEC-3633

Signed-off-by: Shankho Boron Ghosh <shankhoghosh123@gmail.com>
Change-Id: Ia808adc0208052f0591396860ac776e34070d279
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25473
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
16 files changed:
docs/0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host.md
docs/0_Getting_Started/2_Building_AGL_Image/2_Downloading_AGL_Software.md
docs/1_Hardware_Support/Overview.md
docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md [new file with mode: 0644]
docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md [new file with mode: 0644]
docs/5_How_To_Contribute/3_Working_with_Gerrit.md [new file with mode: 0644]
docs/5_How_To_Contribute/4_Submitting_Changes.md [new file with mode: 0644]
docs/5_How_To_Contribute/5_Reviewing_Changes.md [new file with mode: 0644]
docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md [new file with mode: 0644]
docs/5_How_To_Contribute/7_General_Guidelines.md [new file with mode: 0644]
docs/5_How_To_Contribute/8_Adding_Documentation.md [moved from docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md with 67% similarity]
docs/5_How_To_Contribute/images/jira-1.png [new file with mode: 0644]
docs/5_How_To_Contribute/images/jira-2.png [new file with mode: 0644]
docs/5_How_To_Contribute/images/jira-3.png [new file with mode: 0644]
docs/5_How_To_Contribute/images/review.png [new file with mode: 0644]
docs/index.md

index 74877b0..14c6f6e 100644 (file)
@@ -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.
 
index 88e6bb1..39d2c18 100644 (file)
@@ -10,6 +10,8 @@ For information on how to create accounts for Gerrit, see the
 [Getting Started with AGL](https://wiki.automotivelinux.org/start/getting-started)
 wiki page.
 
+**NOTE:** Further information about Download and Build AGL Source Code available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/source-code).
+
 The remainder of this section provides steps on how to download the AGL source files:
 
 1. **Define Your Top-Level Directory:**
index 86f0783..f05237b 100644 (file)
@@ -4,39 +4,41 @@ title: Supported Boards
 
 The following table briefs about the various hardware platforms, supported by AGL :
 
+**NOTE:** Further information about AGL Distribution available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro).
+
 ### AGL Reference Machines
 
 |      BOARD      |    $MACHINE    | ARCHITECHTURE |
 |:---------------:|:--------------:|:-------------:|
 |       QEMU      |   qemu-x86-64  |      x86      |
-|                 |    qemu-arm    |     arm 32    |
-|                 |   qemu-arm64   |     arm 64    |
+|                 |    qemu-arm    |     arm32     |
+|                 |   qemu-arm64   |     arm64     |
 |                 |                |               |
-|    RCar Gen 3   |     h3ulcb     |     arm 64    |
-|                 | h3-salvator-x  |     arm 64    |
-|                 |      h3-kf     |     arm 64    |
-|                 |     m3ulcb     |     arm 64    |
-|                 | m3-salvator-x  |     arm 64    |
-|                 |      m3-kf     |     arm 64    |
+|    RCar Gen 3   |     h3ulcb     |     arm64     |
+|                 | h3-salvator-x  |     arm64     |
+|                 |      h3-kf     |     arm64     |
+|                 |     m3ulcb     |     arm64     |
+|                 | m3-salvator-x  |     arm64     |
+|                 |      m3-kf     |     arm64     |
 |                 |                |               |
-|  Raspberry Pi   |  raspberrypi4  |     arm 64    |
+|  Raspberry Pi   |  raspberrypi4  |     arm64     |
 
 ### Community supported Machines
 
 |    BOARD     |     $MACHINE          | ARCHITECHTURE |
 |:-------------:|:-----------------:|:-------------:|
-|  BeagleBone  |        bbe            |     arm 32    |
-|              |    beaglebone         |     arm 32    |
+|  BeagleBone  |        bbe            |     arm32     |
+|              |    beaglebone         |     arm32     |
 |              |                       |               |
-|   i. MX 6    |      cubox-i          |     arm 32    |
-|              | imx6qdlsabreauto      |     arm 32    |
-|              |    nitrogen6x         |     arm 32    |
+|   i. MX 6    |      cubox-i          |     arm32     |
+|              | imx6qdlsabreauto      |     arm32     |
+|              |    nitrogen6x         |     arm32     |
 |              |                       |               |
-|   i. MX 8    |     imx8mqevk         |     arm 64    |
-|              |   imx8mqevk-viv       |     arm 64    |
+|   i. MX 8    |     imx8mqevk         |     arm64     |
+|              |   imx8mqevk-viv       |     arm64     |
 |              |                       |               |
-|  Snapdragon  | dragonboard-410c      |     arm 64    |
-|              | dragonboard-820c      |     arm 64    |
+|  Snapdragon  | dragonboard-410c      |     arm64     |
+|              | dragonboard-820c      |     arm64     |
 |              |                       |               |
 |    ARC HS    |       hsdk            |      ARC      |
 
@@ -77,7 +79,7 @@ Community supported Machines (i. MX 6, i. MX 8, Snapdragon & ARC HS)
         ```sh
         $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-profile-graphical-html5
 
-        #To enable Developer Options
+        # To enable Developer Options
         $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-profile-graphical-html5 agl-devel
         ```
 
@@ -99,7 +101,7 @@ AGL Reference Boards (QEMU, RCar Gen 3 & Raspberry Pi 4)
     ```sh
     $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-cluster-demo
 
-    #To enable Developer Options
+    # To enable Developer Options
     $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-cluster-demo agl-devel
     ```
 
@@ -123,7 +125,7 @@ Community supported Machines (BeagleBone)
     ```sh
     $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-telematics-demo
 
-    #To enable Developer Options
+    # To enable Developer Options
     $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-telematics-demo agl-devel
     ```
 
diff --git a/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md b/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md
new file mode 100644 (file)
index 0000000..83a974d
--- /dev/null
@@ -0,0 +1,100 @@
+---
+title: Getting Linux Foundation account
+---
+
+In order to participate in the development of the Automotive Grade Linux
+project, you will need a Linux Foundation account. You will need to use
+your LF ID to access to all the AGL community development tools,
+including [Gerrit](http://gerrit.automotivelinux.org/),
+[Jira](https://jira.automotivelinux.org/) and the
+[Wiki](https://wiki.automotivelinux.org/) (for editing, only).
+
+**NOTE:** Further information about Contributing to the AGL Distro
+available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/contributing).
+
+## Creating Linux Foundation ID
+
+ 1. Go to the [Linux Foundation ID website](https://identity.linuxfoundation.org/).
+
+ 2. Select the option `I need to create a Linux Foundation ID`, and fill
+ out the form that appears. (It is advised to authenticate through email
+ instead of logging through Facebook/Google/Github.)
+
+ 3. Wait a few minutes, then look for an email message with the subject
+ line: `Validate your Linux Foundation ID email`.
+
+ 4. Open the received URL to validate your email address.
+
+ 5. Verify that your browser displays the message  ``You have
+ successfully validated your e-mail address``.
+
+ 6. Access [Gerrit](http://gerrit.automotivelinux.org/) by selecting
+ ``Sign In``, and use your new Linux Foundation account ID to sign in.
+
+## Configuring Gerrit to Use SSH
+
+Gerrit uses SSH to interact with your Git client. If you already have an SSH
+key pair, you can skip the part of this section that explains how to generate one.
+
+What follows explains how to generate an SSH key pair in a Linux environment ---
+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"
+ ```
+
+**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.
+
+The generated SSH key pair can be found in the files ``~/.ssh/id_rsa`` and
+``~/.ssh/id_rsa.pub``.
+
+Next, add the private key in the ``id_rsa`` file to your key ring, e.g.:
+
+ ```sh
+ $ ssh-add ~/.ssh/id_rsa
+ ```
+
+Finally, add the public key of the generated key pair to the Gerrit
+server, with the following steps:
+
+1. Go to [Gerrit](http://gerrit.automotivelinux.org/).
+
+2. Click on your account name in the upper right corner.
+
+3. From the pop-up menu, select ``Settings``.
+
+4. On the left side menu, click on ``SSH Public Keys``.
+
+5. Paste the contents of your public key ``~/.ssh/id_rsa.pub`` and click
+   ``Add key``.
+
+**Note:** The ``id_rsa.pub`` file can be opened with any text editor.
+Ensure that all the contents of the file are selected, copied and pasted
+into the ``Add SSH key`` window in Gerrit.
+
+**Note:** The SSH key generation instructions operate on the assumption
+that you are using the default naming. It is possible to generate
+multiple SSH keys and to name the resulting files differently. See the
+[ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) documentation for
+details on how to do that. Once you have generated non-default keys, you
+need to configure SSH to use the correct key for Gerrit. In that case,
+you need to create a ``~/.ssh/config`` file modeled after the one below.
+
+ ```sh 
+host gerrit.automotivelinux.org 
+  HostName gerrit.automotivelinux.org
+  IdentityFile ~/.ssh/id_rsa_automotivelinux_gerrit
+  User <LFID>
+```
+
+`<LFID>` is your Linux Foundation ID and the value of IdentityFile is the
+name of the public key file you generated.
+
+**Warning:** Potential Security Risk! Do not copy your private key
+``~/.ssh/id_rsa``. Use only the public ``~/.ssh/id_rsa.pub``.
+
+
diff --git a/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md b/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md
new file mode 100644 (file)
index 0000000..32475aa
--- /dev/null
@@ -0,0 +1,33 @@
+---
+title: Using Jira for current work items
+---
+
+This document has been created to give further insight into the work in
+progress towards the Automotive Grade Linux architecture based on the
+community roadmap. The requirements for the roadmap are being tracked in
+[Jira](https://jira.automotivelinux.org/).
+
+On this page you will see all the public (and restricted) boards that
+have been created. For example the **Board Name** *CI and Automated Test
+Expert Group*:
+
+![Jira boards](images/jira-2.png)
+
+When you click on *CI and Automated Test Expert Group* under **Board
+name** you will be directed to a page that contains the following
+columns:
+
+![Jira boards](images/jira-3.png)
+
+The meanings to these columns are as follows:
+
+-  **NOT STARTED** – list of items slated for the current sprint (sprints are
+   defined in 2 week iterations), but are not currently in progress
+-  **IN PROGRESS** – items currently being worked by someone in the
+   community.
+-  **DONE** – items merged and complete in the sprint.
+
+If there is an item you are interested in working on, want more
+information or have questions, or if there is an item that you feel needs
+to be in higher priority, please add comments directly to the Jira item.
+All feedback and help is very much appreciated.
\ No newline at end of file
diff --git a/docs/5_How_To_Contribute/3_Working_with_Gerrit.md b/docs/5_How_To_Contribute/3_Working_with_Gerrit.md
new file mode 100644 (file)
index 0000000..8bba660
--- /dev/null
@@ -0,0 +1,148 @@
+---
+title: Working with Gerrit
+---
+
+Follow these instructions to collaborate on AGL through the Gerrit review system.
+
+Please be sure that you are subscribed to the [mailing
+list](https://lists.automotivelinux.org/g/agl-dev-community) and of
+course, you can reach out on IRC at the #automotive channel on
+Freenode.net
+
+Gerrit assigns the following roles to users:
+
+-  **Submitters**: May submit changes for consideration, review other
+   code changes, and make recommendations for acceptance or rejection by
+   voting +1 or -1, respectively.
+-  **Maintainers**: May approve or reject changes based upon feedback
+   from reviewers voting +2 or -2, respectively.
+
+## Getting deeper into Gerrit
+
+A comprehensive walk-through of Gerrit is beyond the scope of this
+document. There are plenty of resources available on the Internet. A good
+summary can be found
+[here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and 
+[Basic Gerrit Walkthrough for GitHub Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html).
+
+## Working with a local clone of the repository
+
+To work on something, whether a new feature or a bugfix:
+
+1. Open the Gerrit [repo page](https://gerrit.automotivelinux.org/gerrit/admin/repos/).
+
+2. Select the repository you wish to work on.
+
+3. Open a terminal window and clone the project locally using the
+   ``Clone with git hook`` URL. Be sure that ``ssh`` is also selected,
+   as this will make authentication much simpler. For example, for `documentation` repository:
+
+    ```sh
+    $ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P
+    29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
+    ```
+
+4. Setup `user` and `email` for git config
+
+    ```sh
+     $ cd documentation
+     $ git.config --global user.name "Your Full Name"
+     $ git config --global user.email "your@email.com"
+    ```
+
+      **NOTE:** To only configure for a particular repository :
+
+    ```sh
+     $ cd documentation
+     $ git.config user.name "Your Full Name"
+     $ git config user.email "your@email.com"
+    ```
+
+5. Create a descriptively-named branch off of your cloned repository
+
+    ```sh
+     $ git checkout -b issue-nname
+    ```
+
+## Using git review
+
+There's a **very** useful tool for working with Gerrit called [git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This command-line tool can automate most of the ensuing sections for you. Ofcourse, reading the information below is also highly recommended so that you understand what's going on behind the scenes.
+
+```sh
+# for first time use only
+$ git review -s
+```
+If `.gitreview` is missing, add the following section to ``.git/config``, and replace ``<LFID>``
+with your LFID id.
+
+```sh
+[remote "gerrit"]
+   url = ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation.git
+   fetch = +refs/heads/*:refs/remotes/gerrit/*
+```
+
+Then submit your change with ``git review``.
+
+```sh
+$ cd documentation
+$ git review
+```
+
+When you update your patch, you can commit with ``git commit --amend``,
+and then repeat the ``git review`` command.
+
+## Typical Review Workflow
+
+   - New Fresh Change
+
+      ```sh
+      $ cd documentation                              # Working Repository
+      $ git remote -v update                          # Updating wrt remote
+      $ git checkout -b mytopicbranch origin/master   # Creating new branch
+      ### CODE the CHANGES
+      $ git add  <file>                               # Track the changed files
+      $ git commit -s                                 # Signed Commit Message
+      $ git review                                    # Submit Changes to review
+      ```
+
+   - Updating existing Gerrit Review
+
+      ```sh
+      $ cd documentation                              # Working Repository
+      $ git review -d 25678                           # Download review, 25678 is change number
+      ### CODE the CHANGES
+      $ git add  <file>                               # Track the changed files
+      $ git commit -s                                 # Signed Commit Message
+      $ git review                                    # Submit Changes to review
+      $ git checkout master                           # Return to master branch
+      ```
+
+## Reviewing Using Gerrit
+
+-  **Add**: This button allows the change submitter to manually add
+   names of people who should review a change; start typing a name and
+   the system will auto-complete based on the list of people registered
+   and with access to the system. They will be notified by email that
+   you are requesting their input.
+
+-  **Abandon**: This button is available to the submitter only; it
+   allows a committer to abandon a change and remove it from the merge
+   queue.
+
+-  **Change-ID**: This ID is generated by Gerrit (or system). It becomes
+   useful when the review process determines that your commit(s) have to
+   be amended. You may submit a new version; and if the same Change-ID
+   header (and value) are present, Gerrit will remember it and present
+   it as another version of the same change.
+
+-  **Status**: Currently, the example change is in review status, as
+   indicated by “Needs Verified” in the upper-left corner. The list of
+   Reviewers will all emit their opinion, voting +1 if they agree to the
+   merge, -1 if they disagree. Gerrit users with a Maintainer role can
+   agree to the merge or refuse it by voting +2 or -2 respectively.
+
+Notifications are sent to the email address in your commit message's
+Signed-off-by line. Visit your [Gerrit dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self),
+to check the progress of your requests.
+
+The history tab in Gerrit will show you the in-line comments and the author of the review.
diff --git a/docs/5_How_To_Contribute/4_Submitting_Changes.md b/docs/5_How_To_Contribute/4_Submitting_Changes.md
new file mode 100644 (file)
index 0000000..36e21f4
--- /dev/null
@@ -0,0 +1,69 @@
+---
+title: Submitting Changes
+---
+
+Carefully review the following before submitting a change. These
+guidelines apply to developers that are new to open source, as well as
+to experienced open source developers.
+
+## Change Requirements
+
+
+This section contains guidelines for submitting code changes for review.
+For more information on how to submit a change using Gerrit, please see
+[Working with Gerrit](./3_Working_with_Gerrit.md).
+
+Changes are submitted as Git commits. Each commit must contain:
+
+-  a short and descriptive subject line that is 72 characters or fewer,
+   followed by a blank line.
+-  a change description with your logic or reasoning for the changes,
+   followed by a blank line
+-  a Signed-off-by line, followed by a colon (Signed-off-by:)
+-  a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit
+   won't accept patches without this identifier.
+
+A commit with the above details is considered well-formed.
+[This page](https://chris.beams.io/posts/git-commit/) is a very useful for the
+same.
+
+All changes and topics sent to Gerrit must be well-formed.
+Informationally, ``commit messages`` must include:
+
+-  **what** the change does,
+-  **why** you chose that approach, and
+-  **how** you know it works -- for example, which tests you ran.
+
+For example: One commit fixes whitespace issues, another renames a
+function and a third one changes the code's functionality. An example
+commit file is illustrated below in detail:
+
+```sh
+
+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>
+```
+
+Include the issue ID in the one line description of your commit message for
+readability. Gerrit will link issue IDs automatically to the corresponding
+entry in Jira.
+
+Each commit must also contain the following line at the bottom of the commit
+message:
+
+```sh
+Signed-off-by: Your Name <your@email.address>
+```
+
+The name in the Signed-off-by line and your email must match the change
+authorship information. Make sure your :file:``.git/config`` is set up
+correctly. Always submit the full set of changes via Gerrit.
+
+When a change is included in the set to enable other changes, but it
+will not be part of the final set, please let the reviewers know this.
diff --git a/docs/5_How_To_Contribute/5_Reviewing_Changes.md b/docs/5_How_To_Contribute/5_Reviewing_Changes.md
new file mode 100644 (file)
index 0000000..14c18bf
--- /dev/null
@@ -0,0 +1,56 @@
+---
+title: Reviewing Changes
+---
+
+1. Click on a link for incoming or outgoing review.
+
+2. The details of the change and its current status are loaded:
+
+      ![review](images/review.png)
+
+      -  **Status:** Displays the current status of the change.
+
+      -  **Reply:** Click on this button after reviewing to add a final review
+         message and a score, -1, 0 or +1.
+
+      -  **Patch Sets:** If multiple revisions of a patch exist, this button
+         enables navigation among revisions to see the changes. By default,
+         the most recent revision is presented.
+
+      -  **Download:** This button brings up another window with multiple
+         options to download or checkout the current changeset. The button on
+         the right copies the line to your clipboard. You can easily paste it
+         into your git interface to work with the patch as you prefer.
+
+         Underneath the commit information, the files that have been changed by
+         this patch are displayed.
+
+3. Click on a filename to review it. Select the code base to
+   differentiate against. The default is ``Base`` and it will generally
+   be what is needed.
+
+4. The review page presents the changes made to the file. At the top of
+   the review, the presentation shows some general navigation options.
+   Navigate through the patch set using the arrows on the top right
+   corner. It is possible to go to the previous or next file in the set
+   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.
+
+5. After adding the comment, it is saved as a *Draft*.
+
+6. Once you have reviewed all files and provided feedback, click the
+   *green up arrow* at the top right to return to the main change page.
+   Click the ``Reply`` button, write some final comments, and submit
+   your score for the patch set. Click ``Post`` to submit the review of
+   each reviewed file, as well as your final comment and score. Gerrit
+   sends an email to the change-submitter and all listed reviewers.
+   Finally, it logs the review for future reference. All individual
+   comments are saved as *Draft* until the ``Post`` button is clicked.
+
+
diff --git a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md
new file mode 100644 (file)
index 0000000..42f39f4
--- /dev/null
@@ -0,0 +1,271 @@
+---
+title: Gerrit Recommended Practices
+---
+
+This document presents some best practices to help you use Gerrit more
+effectively. The intent is to show how content can be submitted easily.
+Use the recommended practices to reduce your troubleshooting time and
+improve participation in the community.
+
+## Commit Messages
+
+Gerrit follows the Git commit message format. Ensure the headers are at
+the bottom and don't contain blank lines between one another. The
+following example shows the format and content expected in a commit
+message:
+
+Brief (no more than 50 chars) one line description.
+
+Elaborate summary of the changes made referencing why (motivation), what
+was changed and how it was tested. Note also any changes to
+documentation made to remain consistent with the code changes, wrapping
+text at 72 chars/line.
+
+```sh
+Bug-AGL: SPEC-<JIRA-ID>
+
+Change-Id: LONGHEXHASH
+Signed-off-by: Your Name your.email\@example.org
+```
+
+The Gerrit server provides a precommit hook to autogenerate the
+Change-Id which is one time use.
+
+**Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
+
+## Avoid Pushing Untested Work to a Gerrit Server
+
+To avoid pushing untested work to Gerrit.
+
+Check your work at least three times before pushing your change to
+Gerrit. Be mindful of what information you are publishing.
+
+## Keeping Track of Changes
+
+-  Set Gerrit to send you emails:
+
+-  Gerrit will add you to the email distribution list for a change if a
+   developer adds you as a reviewer, or if you comment on a specific
+   Patch Set.
+
+-  Opening a change in Gerrit's review interface is a quick way to
+   follow that change.
+
+-  Watch projects in the Gerrit projects section at ``Gerrit``, select
+   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](https://lists.automotivelinux.org/g/agl-dev-community)
+to learn and help others ramp up.
+
+## Topic branches
+
+Topic branches are temporary branches that you push to commit a set of
+logically-grouped dependent commits:
+
+To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed
+as a topic in **TopicName** use the following command as an example:
+
+```sh
+$ git push REMOTE HEAD:refs/for/master/TopicName
+```
+
+The topic will show up in the review ``UI`` and in the
+``Open Changes List``. Topic branches will disappear from the master
+tree when its content is merged.
+
+## Finding Available Topics
+
+```sh
+$ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u
+```
+
+-  [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
+   fabric.
+-  *branch* : The topic is searched at this branch.
+-  *topic* : The name of an specific topic, leave it blank to include them
+   all.
+-  *sort* : Sorts the found topics, in this case by update (-u).
+
+## Downloading or Checking Out a Change
+
+In the review UI, on the top right corner, the **Download** link
+provides a list of commands and hyperlinks to checkout or download diffs
+or files.
+
+We recommend the use of the *git review* plugin. The steps to install
+git review are beyond the scope of this document. Refer to the
+[git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers)
+for the installation process.
+
+To check out a specific change using Git, the following command usually
+works:
+
+```sh
+$ 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
+```
+
+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
+```
+
+## Using Sandbox Branches
+
+You can create your own branches to develop features. The branches are
+pushed to the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location.
+
+These commands ensure the branch is created in Gerrit's server.
+
+```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:
+
+-  develop the code,
+-  break the information into small commits,
+-  submit changes,
+-  apply feedback,
+-  rebase.
+
+The next command pushes forcibly without review:
+
+```sh
+$ git push REMOTE sandbox/USERNAME/BRANCHNAME
+```
+
+You can also push forcibly with review:
+
+```sh
+$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME
+```
+
+## Updating the Version of a Change
+
+During the review process, you might be asked to update your change. It
+is possible to submit multiple versions of the same change. Each version
+of the change is called a patch set.
+
+Always maintain the **Change-Id** that was assigned. For example, there
+is a list of commits, **c0...c7**, which were submitted as a topic
+branch:
+
+```sh
+
+$ git log REMOTE/master..master
+
+  c0
+  ...
+  c7
+
+$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
+```
+
+After you get reviewers' feedback, there are changes in **c3** and
+**c4** that must be fixed. If the fix requires rebasing, rebasing
+changes the commit Ids, see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section for more information. However, you must keep the same Change-Id
+and push the changes again:
+
+```sh
+$ git push REMOTE HEAD:refs/for/master/SOMETOPIC
+```
+
+This new push creates a patches revision, your local history is then
+cleared. However you can still access the history of your changes in
+Gerrit on the ``review UI`` section, for each change.
+
+It is also permitted to add more commits when pushing new versions.
+
+### Rebasing
+
+Rebasing is usually the last step before pushing changes to Gerrit; this
+allows you to make the necessary *Change-Ids*. The *Change-Ids* must be
+kept the same.
+
+-  **squash:** mixes two or more commits into a single one.
+-  **reword:** changes the commit message.
+-  **edit:** changes the commit content.
+-  **reorder:** allows you to interchange the order of the commits.
+-  **rebase:** stacks the commits on top of the master.
+
+## Rebasing During a Pull
+
+Before pushing a rebase to your master, ensure that the history has a
+consecutive order.
+
+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
+
+  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
+```
+
+This pulls **a5-a7** and re-apply **c0-c7** on top of them:
+
+```sh
+$ git log --oneline REMOTE/master..master
+a0
+...
+a7
+c0
+c1
+...
+c7
+```
+
+## Getting Better Logs from Git
+
+Use these commands to change the configuration of Git in order to
+produce better logs:
+
+```sh
+$ git config log.abbrevCommit true
+```
+
+The command above sets the log to abbreviate the commits' hash.
+
+```sh
+$ 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
+```
+
+The command above avoids the insertion of an unnecessary line before the
+Author line.
diff --git a/docs/5_How_To_Contribute/7_General_Guidelines.md b/docs/5_How_To_Contribute/7_General_Guidelines.md
new file mode 100644 (file)
index 0000000..cc0ece5
--- /dev/null
@@ -0,0 +1,170 @@
+---
+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``.
@@ -2,15 +2,22 @@
 title: Adding Documentation
 ---
 
-The [documentation gerrit repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) contains AGL documentation website template and content, rendering is visible at [https://docs-agl.readthedocs.io/en/latest/](https://docs-agl.readthedocs.io/en/latest/). The documentation site is hosted on [readthedocs](https://readthedocs.org/projects/docs-agl/) and corresponding builds are mentioned [here](https://readthedocs.org/projects/docs-agl/builds/).
+The [documentation gerrit repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation)
+contains AGL documentation website template and content, rendering is
+visible at
+[https://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/).
+The documentation site is hosted on
+[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and
+corresponding builds are mentioned
+[here](https://readthedocs.org/projects/automotivegradelinux/builds/).
 
 ## Download Repository
 
 
-Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) and clone with commit-msg hook :
+Clone with commit-msg hook :
 
 ```sh
-$ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
+$ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
 ```
 
 ## Building a local site
@@ -71,12 +78,13 @@ documentation
 
 ## Test Hyperlinks
 
-[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to check all the hyperlinks in the site.
+[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that
+allows to check all the hyperlinks in the site.
 
 For testing hyperlinks as soon as the local site is running, do:
 
 ```sh
-linkchecker http://localhost:8000
+linkchecker http://localhost:8000
 ```
 
 The ```linkchecker``` output will display the broken link and there location
@@ -89,25 +97,25 @@ in the site.
 
     ```sh
     #recent version of git-review  (>=1.28.0 is required)
-    sudo pip3 install git-review 
+    sudo pip3 install git-review 
     ```
 
 2. Write commit message
 
     ```sh
     # track all the new changes
-    git add .
+    git add .
 
     # Write the commit message
-    git commit --signoff
+    git commit --signoff
     ```
 
 3. Push changes for review to Gerrit
 
     ```sh
     # first time only
-    git review -s
+    git review -s
 
     # then to push use
-    git review
+    git review
     ```
\ No newline at end of file
diff --git a/docs/5_How_To_Contribute/images/jira-1.png b/docs/5_How_To_Contribute/images/jira-1.png
new file mode 100644 (file)
index 0000000..4a39bfb
Binary files /dev/null and b/docs/5_How_To_Contribute/images/jira-1.png differ
diff --git a/docs/5_How_To_Contribute/images/jira-2.png b/docs/5_How_To_Contribute/images/jira-2.png
new file mode 100644 (file)
index 0000000..c1cdb21
Binary files /dev/null and b/docs/5_How_To_Contribute/images/jira-2.png differ
diff --git a/docs/5_How_To_Contribute/images/jira-3.png b/docs/5_How_To_Contribute/images/jira-3.png
new file mode 100644 (file)
index 0000000..b1bec2e
Binary files /dev/null and b/docs/5_How_To_Contribute/images/jira-3.png differ
diff --git a/docs/5_How_To_Contribute/images/review.png b/docs/5_How_To_Contribute/images/review.png
new file mode 100644 (file)
index 0000000..805166a
Binary files /dev/null and b/docs/5_How_To_Contribute/images/review.png differ
index b78611a..10cba84 100644 (file)
@@ -45,16 +45,12 @@ The "Getting Started" topics allow you to quickly accomplish some work using
 AGL.
 You can use the "Getting Started" sections to do the following:
 
-* [Quickstart](./0_Getting_Started/1_Quickstart/Quickstart.md) to quickly install the     pre-built images into an emulation or hardware platform.
+* [Quickstart](./0_Getting_Started/1_Quickstart/Using_Ready_Made_Images.md) to quickly install the     pre-built images into an emulation or hardware platform.
 
 * [Learn How to Build an AGL Image](./0_Getting_Started/2_Building_AGL_Image/0_Build_Process.md) by working
   through fundamental steps that show you how to build for various supported
   hardware targets (e.g. Raspberry PI boards).
 
-* [Set Up a Docker Container](./) to create a
-  contained, controlled development environment for building images and
-  Software Development Kits (SDKs) using AGL.
-
 * [Learn How to Create an Application](./app-workflow-intro.html) using the
   application development workflow.