aboutsummaryrefslogtreecommitdiffstats
path: root/docs/5_How_To_Contribute
diff options
context:
space:
mode:
authorShankho Boron Ghosh <shankhoghosh123@gmail.com>2020-10-30 10:23:28 +0530
committerJan-Simon Moeller <jsmoeller@linuxfoundation.org>2020-11-11 13:36:16 +0000
commitda6cd0b6c26ca9a3760d8a89ce68baf83eeaa1b1 (patch)
tree5621912c4960ff1919f4664f95f4c4f62b347e5d /docs/5_How_To_Contribute
parente76766d79c3063b873b75bd2080c654f3f6d71ba (diff)
Added [in-progress] Developer Guides
Updated mkdocs.yml, README.md. Text wrap markdowns at 80. Bug-AGL: [SPEC-3633] Signed-off-by: Shankho Boron Ghosh <shankhoghosh123@gmail.com> Change-Id: I2d7b43cb870e97786d3eb101c60a2071cc50f0be Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25498 Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org> Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Diffstat (limited to 'docs/5_How_To_Contribute')
-rw-r--r--docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md4
-rw-r--r--docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md27
-rw-r--r--docs/5_How_To_Contribute/3_Working_with_Gerrit.md93
-rw-r--r--docs/5_How_To_Contribute/4_Submitting_Changes.md47
-rw-r--r--docs/5_How_To_Contribute/5_Reviewing_Changes.md37
-rw-r--r--docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md148
-rw-r--r--docs/5_How_To_Contribute/7_General_Guidelines.md226
-rw-r--r--docs/5_How_To_Contribute/8_Adding_Documentation.md14
8 files changed, 290 insertions, 306 deletions
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
index 83a974d..c4d8b08 100644
--- a/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md
+++ b/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md
@@ -84,8 +84,8 @@ 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
+ ```sh
+host gerrit.automotivelinux.org
HostName gerrit.automotivelinux.org
IdentityFile ~/.ssh/id_rsa_automotivelinux_gerrit
User <LFID>
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
index 32475aa..49b443d 100644
--- 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
@@ -2,20 +2,18 @@
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
+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*:
+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:
+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)
@@ -23,11 +21,10 @@ 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.
+- **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
+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
index 8bba660..44da2d9 100644
--- a/docs/5_How_To_Contribute/3_Working_with_Gerrit.md
+++ b/docs/5_How_To_Contribute/3_Working_with_Gerrit.md
@@ -2,40 +2,41 @@
title: Working with Gerrit
---
-Follow these instructions to collaborate on AGL through the Gerrit review system.
+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
+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.
+- **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).
+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/).
+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:
+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
@@ -66,14 +67,18 @@ To work on something, whether a new feature or a bugfix:
## 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.
+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.
+If `.gitreview` is missing, add the following section to ``.git/config``, and
+replace ``<LFID>`` with your LFID id.
```sh
[remote "gerrit"]
@@ -88,8 +93,8 @@ $ cd documentation
$ git review
```
-When you update your patch, you can commit with ``git commit --amend``,
-and then repeat the ``git review`` command.
+When you update your patch, you can commit with ``git commit --amend``, and then
+repeat the ``git review`` command.
## Typical Review Workflow
@@ -119,30 +124,30 @@ and then repeat the ``git review`` command.
## 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.
+- **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.
+- **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.
+- **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.
+- **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.
+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.
+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
index 36e21f4..d226450 100644
--- a/docs/5_How_To_Contribute/4_Submitting_Changes.md
+++ b/docs/5_How_To_Contribute/4_Submitting_Changes.md
@@ -2,41 +2,40 @@
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.
+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).
+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 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 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.
+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:
+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:
+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
@@ -51,8 +50,8 @@ 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.
+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:
@@ -65,5 +64,5 @@ 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.
+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
index 14c18bf..e9d6758 100644
--- a/docs/5_How_To_Contribute/5_Reviewing_Changes.md
+++ b/docs/5_How_To_Contribute/5_Reviewing_Changes.md
@@ -14,8 +14,8 @@ title: Reviewing Changes
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.
+ 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
@@ -25,16 +25,15 @@ title: Reviewing Changes
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.
+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.
+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.
@@ -44,13 +43,13 @@ title: Reviewing Changes
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.
+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
index 42f39f4..671c685 100644
--- a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md
+++ b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md
@@ -3,23 +3,21 @@ 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.
+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:
+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.
+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>
@@ -28,52 +26,50 @@ 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.
+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/).
+**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.
+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.
+ 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.
+- 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*.
+- 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.
+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:
+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.
+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
@@ -81,43 +77,40 @@ tree when its content is merged.
$ 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.
+- [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.
+- *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.
+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)
+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:
+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:
+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):
+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
@@ -125,8 +118,8 @@ $ 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.
+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.
@@ -157,13 +150,12 @@ $ 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.
+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:
+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
@@ -176,26 +168,26 @@ $ git log REMOTE/master..master
$ 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:
+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.
+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.
+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.
@@ -208,8 +200,8 @@ kept the same.
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:
+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
@@ -225,8 +217,8 @@ $ git log --oneline REMOTE/master..master
c7
```
-If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull
-with a rebase as follows:
+If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a
+rebase as follows:
```sh
$ git pull --rebase REMOTE master
@@ -247,8 +239,8 @@ c7
## Getting Better Logs from Git
-Use these commands to change the configuration of Git in order to
-produce better logs:
+Use these commands to change the configuration of Git in order to produce better
+logs:
```sh
$ git config log.abbrevCommit true
@@ -260,12 +252,12 @@ The command above sets the log to abbreviate the commits' hash.
$ git config log.abbrev 5
```
-The command above sets the abbreviation length to the last 5 characters
-of the hash.
+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.
+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
index cc0ece5..1cb7d69 100644
--- a/docs/5_How_To_Contribute/7_General_Guidelines.md
+++ b/docs/5_How_To_Contribute/7_General_Guidelines.md
@@ -4,30 +4,28 @@ 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.
+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.
+[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
@@ -35,111 +33,106 @@ 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.
+**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.
+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.
+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.
+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
+- 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.
+ 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.
@@ -149,15 +142,14 @@ exceptions.
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.
+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 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.
@@ -166,5 +158,5 @@ include a sign-off statement in the commit message.
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``.
+You can include this automatically when you commit a change to your local git
+repository using ``git commit -s``.
diff --git a/docs/5_How_To_Contribute/8_Adding_Documentation.md b/docs/5_How_To_Contribute/8_Adding_Documentation.md
index b65e971..d2aad82 100644
--- a/docs/5_How_To_Contribute/8_Adding_Documentation.md
+++ b/docs/5_How_To_Contribute/8_Adding_Documentation.md
@@ -2,9 +2,9 @@
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
+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
@@ -78,8 +78,8 @@ 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:
@@ -87,8 +87,8 @@ For testing hyperlinks as soon as the local site is running, do:
$ linkchecker http://localhost:8000
```
-The ```linkchecker``` output will display the broken link and there location
-in the site.
+The ```linkchecker``` output will display the broken link and there location in
+the site.
## Submitting changes