summaryrefslogtreecommitdiffstats
path: root/docs/7_How_To_Contribute
diff options
context:
space:
mode:
Diffstat (limited to 'docs/7_How_To_Contribute')
-rw-r--r--docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md98
-rw-r--r--docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md30
-rw-r--r--docs/7_How_To_Contribute/3_Working_with_Gerrit.md153
-rw-r--r--docs/7_How_To_Contribute/4_Submitting_Changes.md68
-rw-r--r--docs/7_How_To_Contribute/5_Reviewing_Changes.md55
-rw-r--r--docs/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md263
-rw-r--r--docs/7_How_To_Contribute/7_General_Guidelines.md163
-rw-r--r--docs/7_How_To_Contribute/8_Adding_Documentation.md121
-rw-r--r--docs/7_How_To_Contribute/9_Contribution_Checklist.md60
-rw-r--r--docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md211
-rw-r--r--docs/7_How_To_Contribute/images/jira-1.pngbin0 -> 14224 bytes
-rw-r--r--docs/7_How_To_Contribute/images/jira-2.pngbin0 -> 74302 bytes
-rw-r--r--docs/7_How_To_Contribute/images/jira-3.pngbin0 -> 61399 bytes
-rw-r--r--docs/7_How_To_Contribute/images/review.pngbin0 -> 56853 bytes
14 files changed, 1222 insertions, 0 deletions
diff --git a/docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md b/docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md
new file mode 100644
index 0000000..f2b2cb7
--- /dev/null
+++ b/docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md
@@ -0,0 +1,98 @@
+---
+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:
+**Note:** This guide recommends using ed25519 keys because it has been found that this type works well across all operating systems.
+
+ ```sh
+ $ ssh-keygen -t ed25519 -C "your_name@example.com"
+ ```
+
+**Note:** When you’re prompted to “Enter a file in which to save the key” press Enter. This accepts the default location. Next, it 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_ed25519`` and
+``~/.ssh/id_ed25519.pub``.
+
+Next, add the private key in the ``id_ed25519`` file to your key ring, e.g.:
+
+ ```sh
+ $ ssh-add ~/.ssh/id_ed25519
+ ```
+
+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_ed25519.pub`` and click
+ ``Add key``.
+
+**Note:** The ``id_ed25519.pub`` file can be opened with any text editor or you can run the command ``cat ~/.ssh/id_ed25519.pub`` in your terminal and copy output. 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 with command ``touch ~/.ssh/config`` and add details in config file.
+
+```
+host gerrit.automotivelinux.org
+ HostName gerrit.automotivelinux.org
+ IdentityFile ~/.ssh/id_ed25519
+ User <LFID>
+ Port 29418
+```
+
+`<LFID>` is your Linux Foundation ID(username) 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_ed25519``. Use only the public ``~/.ssh/id_ed25519.pub``.
diff --git a/docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md b/docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md
new file mode 100644
index 0000000..49b443d
--- /dev/null
+++ b/docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md
@@ -0,0 +1,30 @@
+---
+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/7_How_To_Contribute/3_Working_with_Gerrit.md b/docs/7_How_To_Contribute/3_Working_with_Gerrit.md
new file mode 100644
index 0000000..ccd9133
--- /dev/null
+++ b/docs/7_How_To_Contribute/3_Working_with_Gerrit.md
@@ -0,0 +1,153 @@
+---
+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 irc.libera.chat
+
+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/7_How_To_Contribute/4_Submitting_Changes.md b/docs/7_How_To_Contribute/4_Submitting_Changes.md
new file mode 100644
index 0000000..d226450
--- /dev/null
+++ b/docs/7_How_To_Contribute/4_Submitting_Changes.md
@@ -0,0 +1,68 @@
+---
+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/7_How_To_Contribute/5_Reviewing_Changes.md b/docs/7_How_To_Contribute/5_Reviewing_Changes.md
new file mode 100644
index 0000000..e9d6758
--- /dev/null
+++ b/docs/7_How_To_Contribute/5_Reviewing_Changes.md
@@ -0,0 +1,55 @@
+---
+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/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md
new file mode 100644
index 0000000..671c685
--- /dev/null
+++ b/docs/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md
@@ -0,0 +1,263 @@
+---
+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/7_How_To_Contribute/7_General_Guidelines.md b/docs/7_How_To_Contribute/7_General_Guidelines.md
new file mode 100644
index 0000000..66092de
--- /dev/null
+++ b/docs/7_How_To_Contribute/7_General_Guidelines.md
@@ -0,0 +1,163 @@
+---
+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 irc.libera.chat) 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. This is done to ensure that
+the author of the change adhere to follow [**DCO**](https://developercertificate.org/).
+
+```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``.
diff --git a/docs/7_How_To_Contribute/8_Adding_Documentation.md b/docs/7_How_To_Contribute/8_Adding_Documentation.md
new file mode 100644
index 0000000..7797ab5
--- /dev/null
+++ b/docs/7_How_To_Contribute/8_Adding_Documentation.md
@@ -0,0 +1,121 @@
+---
+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://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
+
+
+Clone with commit-msg hook :
+
+```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/"
+```
+
+## Building a local site
+
+1. Change into the directory
+
+ ```sh
+ $ cd documentation
+ ```
+
+2. Install MkDocs and rtd-dropdown theme
+
+ ```sh
+ $ sudo pip install -r requirements.txt
+ ```
+
+3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):
+
+ ```sh
+ $ sudo mkdocs serve
+ ```
+
+Process to **add new or edit existing** markdown files to AGL documentation:
+
+## Directory Structure
+
+Find existing or add new markdowns in the following directory structure.
+
+```sh
+documentation
+├── docs
+│   ├── 0_Getting_Started
+│   │   ├── 1_Quickstart
+│   │   └── 2_Building_AGL_Image
+| ├── .....
+| |
+| ├──<Chapter-Number>_<Chapter-Name>
+| | ├──<Subchapter-Number>_<Subchapter-Name>
+| | | ├──<Index-Number>_<Markdown-Title>.md
+| | | ├── .....
+```
+
+## Markdown Formatting
+
+ 1. Add following at the start of each markdown :
+
+ ```sh
+ ---
+ title: <enter-title>
+ ---
+ ```
+
+ 2. Internal Linking :
+
+ ```sh
+ [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)
+ ```
+
+## Test Hyperlinks
+
+[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
+```
+
+The ```linkchecker``` output will display the broken link and there location in
+the site.
+
+
+## Submitting changes
+
+1. Install Git Review
+
+ ```sh
+ #recent version of git-review  (>=1.28.0 is required)
+ $ sudo pip3 install git-review 
+ ```
+
+2. Write commit message (**Note:** Please follow [submitting changes](./4_Submitting_Changes.md) guideline to write your commit message.)
+
+ ```sh
+ # track all the new changes
+ $ git add .
+
+ # Write the commit message
+ $ git commit --signoff
+ ```
+
+3. Push changes for review to Gerrit
+
+ ```sh
+ # first time only
+ $ git review -s
+
+ # then to push use
+ $ git review
+ ```
diff --git a/docs/7_How_To_Contribute/9_Contribution_Checklist.md b/docs/7_How_To_Contribute/9_Contribution_Checklist.md
new file mode 100644
index 0000000..7d86ada
--- /dev/null
+++ b/docs/7_How_To_Contribute/9_Contribution_Checklist.md
@@ -0,0 +1,60 @@
+---
+title: Contribution Checklist
+---
+
+**Open Source Code Contribution Checklist**
+
+## General
+- [ ] Does the component have a name ? (Pick one fitting the purpose and the project.)
+- [ ] Is a separate git repo required for the component ?
+- [ ] Does the component have a README.md containing all basic information about it ?
+ - [ ] Description.
+ - [ ] Dependencies.
+ - [ ] Build instructions.
+ - [ ] Installation instructions.
+ - [ ] Usage instructions.
+ - [ ] Example invocations.
+- [ ] Does the component have a CONTRIBUTIONS.md file? (Containing all necessary information on how to contribute, e.g. pointing to project website? )
+
+## License
+ - [ ] Is the license an OSI approved open source software license?
+ - [ ] Are all files under an OSI approved open source license?
+ - [ ] Does the component have a LICENSE (or COPYING) file detailing the license of the code?
+ - [ ] Do the source code files have the license mentioned in the header?
+ - [ ] Do the source code files have an SPDX tag? (Note: An SPDX tag can be used in a file header instead of the license note)
+ - [ ] Are there files with other licenses in their header?
+ - [ ] If so, LICENSE should be the for the majority of the files and LICENSE.xyz for the exceptions.
+
+## docs/
+ - [ ] Are there docs/ folder for the component ?
+ - [ ] e.g. Are all APIs described inclusive description, usage and example invocations ?
+ - [ ] e.g. Are all cmdline tools or options described in the documentation ?
+ - [ ] e.g. Is the program flow described ?
+ - [ ] Contain Changelog.md ? (Keep track of major changes in the changelog.)
+
+## tests/
+ - [ ] Must have tests available.
+ - [ ] Must have simple invocation scripts available.
+ - [ ] Must have instructions for CI available.
+ - [ ] Must contribute CI test definitions.
+
+## Git repository
+ - [ ] Must have: a .gitreview file.
+ - [ ] Option: Can have a .gitignore file.
+ - [ ] Option: Can have a .editorconfig file.
+ - [ ] All code needs to build against master.
+ - [ ] Is a backport to a release branch required ?
+ - [ ] Code contributions submitted need to have a Sign-off-by! (Follow [**DCO**](https://developercertificate.org/).)
+
+## Yocto/OE
+ - [ ] Recipes need to follow the guidelines of : [**new-recipe-writing-a-new-recipe**](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#new-recipe-writing-a-new-recipe).
+ - [ ] Recipes follow the [**bitbake style guide**](https://www.openembedded.org/wiki/Styleguide).
+ - [ ] Your 'meta-*' layer needs to pass the yocto-check-layer tool.
+
+## Gerrit Reviews
+**All gerrit reviews need to be addressed. All issues are to be discussed with the experts.**
+
+ - [ ] Issues are to be discussed in the EG first.
+ - [ ] Consent needs to be reached.
+ - [ ] Gerrit commits need two upvotes (not from authors!) to be merged.
+ - [ ] Uploads should be 'ready for review' or marked 'WIP'. \ No newline at end of file
diff --git a/docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md b/docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md
new file mode 100644
index 0000000..f445b8c
--- /dev/null
+++ b/docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md
@@ -0,0 +1,211 @@
+
+## Prerequisites ##
+
+As well as the packages docker, docker-compose and pyyaml mentioned in the top
+
+level README, you will need the following:
+
+
+
+1) The following ports are forwarded to docker and therefore need to be kept free
+
+on the host machine:
+
+- 69/UDP: proxyfied to the slave for TFTP
+
+- 80: proxyfied to the slave for TODO (transfer overlay)
+
+- 5500: proxyfied to the slave for Notification
+
+- 55950-56000: proxyfied to the slave for NBD
+
+2) You will need a remote power switch to remotely power the DUTs on and off.
+
+3) You need to have an account with lava.automotivelinux.org. Please contact the
+
+agl-dev-community mailing list if you would like an account, and include that you would
+
+like to create your own lab in the email so that the relevant user permissions
+
+can be set.
+
+
+
+## Steps to create your own LAVA lab ##
+
+
+
+1) Clone AGL lava-docker image:
+
+```
+
+git clone https://git.automotivelinux.org/AGL/lava-docker.git
+
+cd lava-docker
+
+```
+
+
+
+2) On the LAVA master web GUI, create a new API token:
+
+https://lava.automotivelinux.org/api/tokens/
+
+
+
+3) Connect all the DUTs' serial to usb and ethernet connections to the host.
+
+
+4) Edit the boards.yaml file:
+
+- Copy the API token you created in step 2 in the place of <generated_lab_token>.
+
+- Add details of each board connected to the lab. See the top level README for
+
+instructions. You will need the following:
+
+- any custom options you require in the kernel args
+
+- uart idvendor, idproduct, devpath
+
+- power on, off and reset commads for the power switch
+
+
+
+To get the uart idvendor and idproduct, unplug and re-plugin the USB cable of the
+
+device in question and then find the details in the latest output of:
+
+```
+
+sudo dmesg | grep idvendor
+
+```
+
+
+
+To get the uart devpath, run the command:
+
+```
+
+udevadm info -a -n /dev/ttyUSB1 |grep devpath | head -n1
+
+```
+
+
+
+NOTE: Make sure you have at least one "board" included. (It is easiest to keep
+
+qemu).
+
+
+
+5) Run the automated setup script:
+
+```
+
+./start.sh slave
+
+```
+
+
+
+7) Check the web GUI to see if the lab has successfully connected to the LAVA
+
+master: https://lava.automotivelinux.org/scheduler/allworkers. If it isn't, run the
+
+following command for debugging:
+
+```
+
+docker-exec -it <name_of_docker_container> cat /var/log/lava-dispatcher/lava-slave.log
+
+```
+
+To identify the container name run the following to list the running containers:
+
+```
+
+docker ps
+
+```
+
+
+
+LAVA logs can be found in `/var/log/lava-dispatcher/`.
+
+
+
+8) Helper scripts
+
+There are a few helper scripts to automate starting/stopping the lab.
+
+```
+
+./start.sh slave
+
+./restart.sh slave
+
+./stop.sh slave
+
+```
+
+
+
+## Adding new device-type templates ##
+
+
+
+Not all device types are supported by default. Templates for new devices will
+
+need to be added to the LAVA master. Please submit new templates to the agl-dev-community
+
+mailing list.
+
+
+
+Before you submit any new device-type templates, please verify that they work.
+
+You can verify that they work in LAVA by carrying out the following instructions:
+
+1) Install lavacli on Debian Stretch or Ubuntu 18.04 and later (if you don't
+
+have a compatible OS, please see https://lava.automotivelinux.org/api/help/ for an
+
+alternative way to use the API)
+
+2) Create your lavacli config file
+
+```
+
+touch ~/.config/lavacli.yaml
+
+```
+
+3) Configure this file to look like the following (note: use the first token
+
+created in https://lava.automotivelinux.org/api/tokens/)
+
+```
+
+default:
+
+uri: https://lava.automotivelinux.org/RPC2
+
+username: <username>
+
+token: <API_token>
+
+```
+
+4) Add your device template to the master
+
+```
+
+lavacli device-types template set <device-type-name> <device-type-name>.yaml
+
+```
+
+NOTE: make sure your device-type templates always follow the following naming scheme:
+
+```<device-type-name>.yaml```
diff --git a/docs/7_How_To_Contribute/images/jira-1.png b/docs/7_How_To_Contribute/images/jira-1.png
new file mode 100644
index 0000000..4a39bfb
--- /dev/null
+++ b/docs/7_How_To_Contribute/images/jira-1.png
Binary files differ
diff --git a/docs/7_How_To_Contribute/images/jira-2.png b/docs/7_How_To_Contribute/images/jira-2.png
new file mode 100644
index 0000000..c1cdb21
--- /dev/null
+++ b/docs/7_How_To_Contribute/images/jira-2.png
Binary files differ
diff --git a/docs/7_How_To_Contribute/images/jira-3.png b/docs/7_How_To_Contribute/images/jira-3.png
new file mode 100644
index 0000000..b1bec2e
--- /dev/null
+++ b/docs/7_How_To_Contribute/images/jira-3.png
Binary files differ
diff --git a/docs/7_How_To_Contribute/images/review.png b/docs/7_How_To_Contribute/images/review.png
new file mode 100644
index 0000000..805166a
--- /dev/null
+++ b/docs/7_How_To_Contribute/images/review.png
Binary files differ