diff options
Diffstat (limited to 'docs/5_How_To_Contribute')
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*:  -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:  @@ -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 |