diff options
Diffstat (limited to 'docs/5_How_To_Contribute')
| -rw-r--r-- | docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md | 100 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md | 33 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/3_Working_with_Gerrit.md | 148 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/4_Submitting_Changes.md | 69 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/5_Reviewing_Changes.md | 56 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md | 271 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/7_General_Guidelines.md | 170 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/8_Adding_Documentation.md (renamed from docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md) | 28 | ||||
| -rw-r--r-- | docs/5_How_To_Contribute/images/jira-1.png | bin | 0 -> 14224 bytes | |||
| -rw-r--r-- | docs/5_How_To_Contribute/images/jira-2.png | bin | 0 -> 74302 bytes | |||
| -rw-r--r-- | docs/5_How_To_Contribute/images/jira-3.png | bin | 0 -> 61399 bytes | |||
| -rw-r--r-- | docs/5_How_To_Contribute/images/review.png | bin | 0 -> 56853 bytes |
12 files changed, 865 insertions, 10 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 new file mode 100644 index 0000000..83a974d --- /dev/null +++ b/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md @@ -0,0 +1,100 @@ +--- +title: Getting Linux Foundation account +--- + +In order to participate in the development of the Automotive Grade Linux +project, you will need a Linux Foundation account. You will need to use +your LF ID to access to all the AGL community development tools, +including [Gerrit](http://gerrit.automotivelinux.org/), +[Jira](https://jira.automotivelinux.org/) and the +[Wiki](https://wiki.automotivelinux.org/) (for editing, only). + +**NOTE:** Further information about Contributing to the AGL Distro +available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/contributing). + +## Creating Linux Foundation ID + + 1. Go to the [Linux Foundation ID website](https://identity.linuxfoundation.org/). + + 2. Select the option `I need to create a Linux Foundation ID`, and fill + out the form that appears. (It is advised to authenticate through email + instead of logging through Facebook/Google/Github.) + + 3. Wait a few minutes, then look for an email message with the subject + line: `Validate your Linux Foundation ID email`. + + 4. Open the received URL to validate your email address. + + 5. Verify that your browser displays the message ``You have + successfully validated your e-mail address``. + + 6. Access [Gerrit](http://gerrit.automotivelinux.org/) by selecting + ``Sign In``, and use your new Linux Foundation account ID to sign in. + +## Configuring Gerrit to Use SSH + +Gerrit uses SSH to interact with your Git client. If you already have an SSH +key pair, you can skip the part of this section that explains how to generate one. + +What follows explains how to generate an SSH key pair in a Linux environment --- +follow the equivalent steps on your OS. + +First, create an SSH key pair with the command: + + ```sh + $ ssh-keygen -t rsa -C "John Doe john.doe@example.com" + ``` + +**Note:** This will ask you for a password to protect the private key as +it generates a unique key. Please keep this password private, and DO NOT +enter a blank password. + +The generated SSH key pair can be found in the files ``~/.ssh/id_rsa`` and +``~/.ssh/id_rsa.pub``. + +Next, add the private key in the ``id_rsa`` file to your key ring, e.g.: + + ```sh + $ ssh-add ~/.ssh/id_rsa + ``` + +Finally, add the public key of the generated key pair to the Gerrit +server, with the following steps: + +1. Go to [Gerrit](http://gerrit.automotivelinux.org/). + +2. Click on your account name in the upper right corner. + +3. From the pop-up menu, select ``Settings``. + +4. On the left side menu, click on ``SSH Public Keys``. + +5. Paste the contents of your public key ``~/.ssh/id_rsa.pub`` and click + ``Add key``. + +**Note:** The ``id_rsa.pub`` file can be opened with any text editor. +Ensure that all the contents of the file are selected, copied and pasted +into the ``Add SSH key`` window in Gerrit. + +**Note:** The SSH key generation instructions operate on the assumption +that you are using the default naming. It is possible to generate +multiple SSH keys and to name the resulting files differently. See the +[ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) documentation for +details on how to do that. Once you have generated non-default keys, you +need to configure SSH to use the correct key for Gerrit. In that case, +you need to create a ``~/.ssh/config`` file modeled after the one below. + + ```sh +host gerrit.automotivelinux.org + HostName gerrit.automotivelinux.org + IdentityFile ~/.ssh/id_rsa_automotivelinux_gerrit + User <LFID> +``` + +`<LFID>` is your Linux Foundation ID and the value of IdentityFile is the +name of the public key file you generated. + +**Warning:** Potential Security Risk! Do not copy your private key +``~/.ssh/id_rsa``. Use only the public ``~/.ssh/id_rsa.pub``. + + diff --git a/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md b/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md new file mode 100644 index 0000000..32475aa --- /dev/null +++ b/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md @@ -0,0 +1,33 @@ +--- +title: Using Jira for current work items +--- + +This document has been created to give further insight into the work in +progress towards the Automotive Grade Linux architecture based on the +community roadmap. The requirements for the roadmap are being tracked in +[Jira](https://jira.automotivelinux.org/). + +On this page you will see all the public (and restricted) boards that +have been created. For example the **Board Name** *CI and Automated Test +Expert Group*: + + + +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: + + + +The meanings to these columns are as follows: + +- **NOT STARTED** – list of items slated for the current sprint (sprints are + defined in 2 week iterations), but are not currently in progress +- **IN PROGRESS** – items currently being worked by someone in the + community. +- **DONE** – items merged and complete in the sprint. + +If there is an item you are interested in working on, want more +information or have questions, or if there is an item that you feel needs +to be in higher priority, please add comments directly to the Jira item. +All feedback and help is very much appreciated.
\ No newline at end of file diff --git a/docs/5_How_To_Contribute/3_Working_with_Gerrit.md b/docs/5_How_To_Contribute/3_Working_with_Gerrit.md new file mode 100644 index 0000000..8bba660 --- /dev/null +++ b/docs/5_How_To_Contribute/3_Working_with_Gerrit.md @@ -0,0 +1,148 @@ +--- +title: Working with Gerrit +--- + +Follow these instructions to collaborate on AGL through the Gerrit review system. + +Please be sure that you are subscribed to the [mailing +list](https://lists.automotivelinux.org/g/agl-dev-community) and of +course, you can reach out on IRC at the #automotive channel on +Freenode.net + +Gerrit assigns the following roles to users: + +- **Submitters**: May submit changes for consideration, review other + code changes, and make recommendations for acceptance or rejection by + voting +1 or -1, respectively. +- **Maintainers**: May approve or reject changes based upon feedback + from reviewers voting +2 or -2, respectively. + +## Getting deeper into Gerrit + +A comprehensive walk-through of Gerrit is beyond the scope of this +document. There are plenty of resources available on the Internet. A good +summary can be found +[here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and +[Basic Gerrit Walkthrough for GitHub Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html). + +## Working with a local clone of the repository + +To work on something, whether a new feature or a bugfix: + +1. Open the Gerrit [repo page](https://gerrit.automotivelinux.org/gerrit/admin/repos/). + +2. Select the repository you wish to work on. + +3. Open a terminal window and clone the project locally using the + ``Clone with git hook`` URL. Be sure that ``ssh`` is also selected, + as this will make authentication much simpler. For example, for `documentation` repository: + + ```sh + $ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P + 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" + ``` + +4. Setup `user` and `email` for git config + + ```sh + $ cd documentation + $ git.config --global user.name "Your Full Name" + $ git config --global user.email "your@email.com" + ``` + + **NOTE:** To only configure for a particular repository : + + ```sh + $ cd documentation + $ git.config user.name "Your Full Name" + $ git config user.email "your@email.com" + ``` + +5. Create a descriptively-named branch off of your cloned repository + + ```sh + $ git checkout -b issue-nname + ``` + +## Using git review + +There's a **very** useful tool for working with Gerrit called [git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This command-line tool can automate most of the ensuing sections for you. Ofcourse, reading the information below is also highly recommended so that you understand what's going on behind the scenes. + +```sh +# for first time use only +$ git review -s +``` +If `.gitreview` is missing, add the following section to ``.git/config``, and replace ``<LFID>`` +with your LFID id. + +```sh +[remote "gerrit"] + url = ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation.git + fetch = +refs/heads/*:refs/remotes/gerrit/* +``` + +Then submit your change with ``git review``. + +```sh +$ cd documentation +$ git review +``` + +When you update your patch, you can commit with ``git commit --amend``, +and then repeat the ``git review`` command. + +## Typical Review Workflow + + - New Fresh Change + + ```sh + $ cd documentation # Working Repository + $ git remote -v update # Updating wrt remote + $ git checkout -b mytopicbranch origin/master # Creating new branch + ### CODE the CHANGES + $ git add <file> # Track the changed files + $ git commit -s # Signed Commit Message + $ git review # Submit Changes to review + ``` + + - Updating existing Gerrit Review + + ```sh + $ cd documentation # Working Repository + $ git review -d 25678 # Download review, 25678 is change number + ### CODE the CHANGES + $ git add <file> # Track the changed files + $ git commit -s # Signed Commit Message + $ git review # Submit Changes to review + $ git checkout master # Return to master branch + ``` + +## Reviewing Using Gerrit + +- **Add**: This button allows the change submitter to manually add + names of people who should review a change; start typing a name and + the system will auto-complete based on the list of people registered + and with access to the system. They will be notified by email that + you are requesting their input. + +- **Abandon**: This button is available to the submitter only; it + allows a committer to abandon a change and remove it from the merge + queue. + +- **Change-ID**: This ID is generated by Gerrit (or system). It becomes + useful when the review process determines that your commit(s) have to + be amended. You may submit a new version; and if the same Change-ID + header (and value) are present, Gerrit will remember it and present + it as another version of the same change. + +- **Status**: Currently, the example change is in review status, as + indicated by “Needs Verified” in the upper-left corner. The list of + Reviewers will all emit their opinion, voting +1 if they agree to the + merge, -1 if they disagree. Gerrit users with a Maintainer role can + agree to the merge or refuse it by voting +2 or -2 respectively. + +Notifications are sent to the email address in your commit message's +Signed-off-by line. Visit your [Gerrit dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self), +to check the progress of your requests. + +The history tab in Gerrit will show you the in-line comments and the author of the review. diff --git a/docs/5_How_To_Contribute/4_Submitting_Changes.md b/docs/5_How_To_Contribute/4_Submitting_Changes.md new file mode 100644 index 0000000..36e21f4 --- /dev/null +++ b/docs/5_How_To_Contribute/4_Submitting_Changes.md @@ -0,0 +1,69 @@ +--- +title: Submitting Changes +--- + +Carefully review the following before submitting a change. These +guidelines apply to developers that are new to open source, as well as +to experienced open source developers. + +## Change Requirements + + +This section contains guidelines for submitting code changes for review. +For more information on how to submit a change using Gerrit, please see +[Working with Gerrit](./3_Working_with_Gerrit.md). + +Changes are submitted as Git commits. Each commit must contain: + +- a short and descriptive subject line that is 72 characters or fewer, + followed by a blank line. +- a change description with your logic or reasoning for the changes, + followed by a blank line +- a Signed-off-by line, followed by a colon (Signed-off-by:) +- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit + won't accept patches without this identifier. + +A commit with the above details is considered well-formed. +[This page](https://chris.beams.io/posts/git-commit/) is a very useful for the +same. + +All changes and topics sent to Gerrit must be well-formed. +Informationally, ``commit messages`` must include: + +- **what** the change does, +- **why** you chose that approach, and +- **how** you know it works -- for example, which tests you ran. + +For example: One commit fixes whitespace issues, another renames a +function and a third one changes the code's functionality. An example +commit file is illustrated below in detail: + +```sh + +A short description of your change with no period at the end + +You can add more details here in several paragraphs, but please keep each line +width less than 80 characters. A bug fix should include the issue number. + +Bug-AGL: [SPEC-<JIRA-ID>] +Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 +Signed-off-by: Your Name <commit-sender@email.address> +``` + +Include the issue ID in the one line description of your commit message for +readability. Gerrit will link issue IDs automatically to the corresponding +entry in Jira. + +Each commit must also contain the following line at the bottom of the commit +message: + +```sh +Signed-off-by: Your Name <your@email.address> +``` + +The name in the Signed-off-by line and your email must match the change +authorship information. Make sure your :file:``.git/config`` is set up +correctly. Always submit the full set of changes via Gerrit. + +When a change is included in the set to enable other changes, but it +will not be part of the final set, please let the reviewers know this. diff --git a/docs/5_How_To_Contribute/5_Reviewing_Changes.md b/docs/5_How_To_Contribute/5_Reviewing_Changes.md new file mode 100644 index 0000000..14c18bf --- /dev/null +++ b/docs/5_How_To_Contribute/5_Reviewing_Changes.md @@ -0,0 +1,56 @@ +--- +title: Reviewing Changes +--- + +1. Click on a link for incoming or outgoing review. + +2. The details of the change and its current status are loaded: + +  + + - **Status:** Displays the current status of the change. + + - **Reply:** Click on this button after reviewing to add a final review + message and a score, -1, 0 or +1. + + - **Patch Sets:** If multiple revisions of a patch exist, this button + enables navigation among revisions to see the changes. By default, + the most recent revision is presented. + + - **Download:** This button brings up another window with multiple + options to download or checkout the current changeset. The button on + the right copies the line to your clipboard. You can easily paste it + into your git interface to work with the patch as you prefer. + + Underneath the commit information, the files that have been changed by + this patch are displayed. + +3. Click on a filename to review it. Select the code base to + differentiate against. The default is ``Base`` and it will generally + be what is needed. + +4. The review page presents the changes made to the file. At the top of + the review, the presentation shows some general navigation options. + Navigate through the patch set using the arrows on the top right + corner. It is possible to go to the previous or next file in the set + or to return to the main change screen. Click on the yellow sticky + pad to add comments to the whole file. + + The focus of the page is on the comparison window. The changes made are + presented in green on the right versus the base version on the left. + Double click to highlight the text within the actual change to provide + feedback on a specific section of the code. Press *c* once the code is + highlighted to add comments to that section. + +5. After adding the comment, it is saved as a *Draft*. + +6. Once you have reviewed all files and provided feedback, click the + *green up arrow* at the top right to return to the main change page. + Click the ``Reply`` button, write some final comments, and submit + your score for the patch set. Click ``Post`` to submit the review of + each reviewed file, as well as your final comment and score. Gerrit + sends an email to the change-submitter and all listed reviewers. + Finally, it logs the review for future reference. All individual + comments are saved as *Draft* until the ``Post`` button is clicked. + + diff --git a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md new file mode 100644 index 0000000..42f39f4 --- /dev/null +++ b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md @@ -0,0 +1,271 @@ +--- +title: Gerrit Recommended Practices +--- + +This document presents some best practices to help you use Gerrit more +effectively. The intent is to show how content can be submitted easily. +Use the recommended practices to reduce your troubleshooting time and +improve participation in the community. + +## Commit Messages + +Gerrit follows the Git commit message format. Ensure the headers are at +the bottom and don't contain blank lines between one another. The +following example shows the format and content expected in a commit +message: + +Brief (no more than 50 chars) one line description. + +Elaborate summary of the changes made referencing why (motivation), what +was changed and how it was tested. Note also any changes to +documentation made to remain consistent with the code changes, wrapping +text at 72 chars/line. + +```sh +Bug-AGL: SPEC-<JIRA-ID> + +Change-Id: LONGHEXHASH +Signed-off-by: Your Name your.email\@example.org +``` + +The Gerrit server provides a precommit hook to autogenerate the +Change-Id which is one time use. + +**Recommended reading:** [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/). + +## Avoid Pushing Untested Work to a Gerrit Server + +To avoid pushing untested work to Gerrit. + +Check your work at least three times before pushing your change to +Gerrit. Be mindful of what information you are publishing. + +## Keeping Track of Changes + +- Set Gerrit to send you emails: + +- Gerrit will add you to the email distribution list for a change if a + developer adds you as a reviewer, or if you comment on a specific + Patch Set. + +- Opening a change in Gerrit's review interface is a quick way to + follow that change. + +- Watch projects in the Gerrit projects section at ``Gerrit``, select + at least *New Changes, New Patch Sets, All Comments* and *Submitted + Changes*. + +Always track the projects you are working on; also see the +feedback/comments [mailing list](https://lists.automotivelinux.org/g/agl-dev-community) +to learn and help others ramp up. + +## Topic branches + +Topic branches are temporary branches that you push to commit a set of +logically-grouped dependent commits: + +To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed +as a topic in **TopicName** use the following command as an example: + +```sh +$ git push REMOTE HEAD:refs/for/master/TopicName +``` + +The topic will show up in the review ``UI`` and in the +``Open Changes List``. Topic branches will disappear from the master +tree when its content is merged. + +## Finding Available Topics + +```sh +$ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u +``` + +- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the current URL where the project is hosted. +- *status* : Indicates the topic's current status: open , merged, + abandoned, draft, merge conflict. +- *project* : Refers to the current name of the project, in this case + fabric. +- *branch* : The topic is searched at this branch. +- *topic* : The name of an specific topic, leave it blank to include them + all. +- *sort* : Sorts the found topics, in this case by update (-u). + +## Downloading or Checking Out a Change + +In the review UI, on the top right corner, the **Download** link +provides a list of commands and hyperlinks to checkout or download diffs +or files. + +We recommend the use of the *git review* plugin. The steps to install +git review are beyond the scope of this document. Refer to the +[git review documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) +for the installation process. + +To check out a specific change using Git, the following command usually +works: + +```sh +$ git review -d CHANGEID +``` + +If you don't have Git-review installed, the following commands will do +the same thing: + +```sh +$ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD +``` + +For example, for the 4th version of change 2464, NN is the first two +digits (24): + +```sh +$ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD +``` + +## Using Sandbox Branches + +You can create your own branches to develop features. The branches are +pushed to the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. + +These commands ensure the branch is created in Gerrit's server. + +```sh +$ git checkout -b sandbox/USERNAME/BRANCHNAME +$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME +``` + +Usually, the process to create content is: + +- develop the code, +- break the information into small commits, +- submit changes, +- apply feedback, +- rebase. + +The next command pushes forcibly without review: + +```sh +$ git push REMOTE sandbox/USERNAME/BRANCHNAME +``` + +You can also push forcibly with review: + +```sh +$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME +``` + +## Updating the Version of a Change + +During the review process, you might be asked to update your change. It +is possible to submit multiple versions of the same change. Each version +of the change is called a patch set. + +Always maintain the **Change-Id** that was assigned. For example, there +is a list of commits, **c0...c7**, which were submitted as a topic +branch: + +```sh + +$ git log REMOTE/master..master + + c0 + ... + c7 + +$ git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +After you get reviewers' feedback, there are changes in **c3** and +**c4** that must be fixed. If the fix requires rebasing, rebasing +changes the commit Ids, see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section for more information. However, you must keep the same Change-Id +and push the changes again: + +```sh +$ git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +This new push creates a patches revision, your local history is then +cleared. However you can still access the history of your changes in +Gerrit on the ``review UI`` section, for each change. + +It is also permitted to add more commits when pushing new versions. + +### Rebasing + +Rebasing is usually the last step before pushing changes to Gerrit; this +allows you to make the necessary *Change-Ids*. The *Change-Ids* must be +kept the same. + +- **squash:** mixes two or more commits into a single one. +- **reword:** changes the commit message. +- **edit:** changes the commit content. +- **reorder:** allows you to interchange the order of the commits. +- **rebase:** stacks the commits on top of the master. + +## Rebasing During a Pull + +Before pushing a rebase to your master, ensure that the history has a +consecutive order. + +For example, your ``REMOTE/master`` has the list of commits from **a0** +to **a4**; Then, your changes **c0...c7** are on top of **a4**; thus: + +```sh +$ git log --oneline REMOTE/master..master + + a0 + a1 + a2 + a3 + a4 + c0 + c1 + ... + c7 +``` + +If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull +with a rebase as follows: + +```sh +$ git pull --rebase REMOTE master +``` + +This pulls **a5-a7** and re-apply **c0-c7** on top of them: + +```sh +$ git log --oneline REMOTE/master..master +a0 +... +a7 +c0 +c1 +... +c7 +``` + +## Getting Better Logs from Git + +Use these commands to change the configuration of Git in order to +produce better logs: + +```sh +$ git config log.abbrevCommit true +``` + +The command above sets the log to abbreviate the commits' hash. + +```sh +$ git config log.abbrev 5 +``` + +The command above sets the abbreviation length to the last 5 characters +of the hash. + +```sh +$ git config format.pretty oneline +``` + +The command above avoids the insertion of an unnecessary line before the +Author line. diff --git a/docs/5_How_To_Contribute/7_General_Guidelines.md b/docs/5_How_To_Contribute/7_General_Guidelines.md new file mode 100644 index 0000000..cc0ece5 --- /dev/null +++ b/docs/5_How_To_Contribute/7_General_Guidelines.md @@ -0,0 +1,170 @@ +--- +title: General Guidelines +--- + +## Getting help + +If you are looking for something to work on, or need some expert +assistance in debugging a problem or working out a fix to an issue, our +community is always eager to help. We hang out on various +[developer meetings](https://www.automotivelinux.org/developer-meetings/), +IRC (#automotive on freenode.net) and the +[mailing lists](https://lists.automotivelinux.org/g/agl-dev-community). +We will be glad to help. The only silly question is the one you don't ask. +Questions are in fact a great way to help improve the project as they highlight +where our documentation could be clearer. + +## Reporting bugs + +If you are a user and you have found a bug, please submit an issue using +[JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA +issue, please try to search the existing items to be sure no one else has +previously reported it. If it has been previously reported, then you +might add a comment that you also are interested in seeing the defect +fixed. + +If it has not been previously reported, create a new JIRA. Please try to +provide sufficient information for someone else to reproduce the issue. +One of the project's maintainers should respond to your issue within 24 +hours. If not, please bump the issue with a comment and request that it +be reviewed. + +## Submitting your fix + +If you just submitted a JIRA for a bug you've discovered, and would like to +provide a fix, we would welcome that gladly! Please assign the JIRA issue to +yourself, then you can submit a change request (CR). + +**NOTE:** If you need help with submitting your first CR, we have created +a brief [tutorial](./4_Submitting_Changes.md) for you. + +## Fixing issues and working stories + +Review the [open issue list](https://jira.automotivelinux.org/issues/?filter=-5) and find +something that interests you. It is wise to start with something +relatively straight forward and achievable, and that no one is already +assigned. If no one is assigned, then assign the issue to yourself. +Please be considerate and rescind the assignment if you cannot finish in +a reasonable time, or add a comment saying that you are still actively +working the issue if you need a little more time. + +## Reviewing submitted Change Requests (CRs) + +Another way to contribute and learn about Automotive Grade Linux is to help the +maintainers with the review of the CRs that are open. Indeed +maintainers have the difficult role of having to review all the CRs +that are being submitted and evaluate whether they should be merged or +not. You can review the code and/or documentation changes, test the +changes, and tell the submitters and maintainers what you think. Once +your review and/or test is complete just reply to the CR with your +findings, by adding comments and/or voting. A comment saying something +like "I tried it on system X and it works" or possibly "I got an error +on system X: xxx " will help the maintainers in their evaluation. As a +result, maintainers will be able to process CRs faster and everybody +will gain from it. + +Just browse through the [open CRs on Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started. + +## Making Feature/Enhancement Proposals + +Review [JIRA](https://jira.automotivelinux.org/) to be sure that there +isn't already an open (or recently closed) proposal for the same +function. If there isn't, to make a proposal we recommend that you open a +JIRA Epic, Story or Improvement, whichever seems to best fit the +circumstance and link or inline a "one pager" of the proposal that states +what the feature would do and, if possible, how it might be implemented. +It would help also to make a case for why the feature should be added, +such as identifying specific use case(s) for which the feature is needed +and a case for what the benefit would be should the feature be +implemented. Once the JIRA issue is created, and the "one pager" either +attached, inlined in the description field, or a link to a publicly +accessible document is added to the description, send an introductory +email to the [agl-dev community](mailto:agl-dev-community@lists.automotivelinux.org) mailing +list linking the JIRA issue, and soliciting feedback. + +Discussion of the proposed feature should be conducted in the JIRA issue +itself, so that we have a consistent pattern within our community as to +where to find design discussion. + +Getting the support of three or more of the AGL maintainers for the new +feature will greatly enhance the probability that the feature's related +CRs will be merged. + +## What makes a good change request? + +- One change at a time. Not five, not three, not ten. One and only one. + Why? Because it limits the blast area of the change. If we have a + regression, it is much easier to identify the culprit commit than if + we have some composite change that impacts more of the code. + +- Include a link to the JIRA story for the change. Why? Because a) we + want to track our velocity to better judge what we think we can + deliver and when and b) because we can justify the change more + effectively. In many cases, there should be some discussion around a + proposed change and we want to link back to that from the change + itself. + +- Include unit and integration tests (or changes to existing tests) + with every change. This does not mean just happy path testing, + either. It also means negative testing of any defensive code that it + correctly catches input errors. When you write code, you are + responsible to test it and provide the tests that demonstrate that + your change does what it claims. Why? Because without this we have no + clue whether our current code base actually works. + +- Minimize the lines of code per CR. Why? If you send a 1,000 or 2,000 +LOC change, how long do you think it takes to review all of that code? +Keep your changes to < 200-300 LOC, if possible. If you have a larger +change, decompose it into multiple independent changess. If you are +adding a bunch of new functions to fulfill the requirements of a new +capability, add them separately with their tests, and then write the code +that uses them to deliver the capability. Of course, there are always +exceptions. If you add a small change and then add 300 LOC of tests, you +will be forgiven;-) If you need to make a change that has broad impact or +a bunch of generated code (protobufs, etc.). Again, there can be +exceptions. + + **NOTE:** Large change requests, e.g. those with more than 300 LOC + are more likely than not going to receive a -2, and you'll be asked + to refactor the change to conform with this guidance. + +- Do not stack change requests (e.g. submit a CR from the same local branch + as your previous CR) unless they are related. This will minimize merge + conflicts and allow changes to be merged more quickly. If you stack requests + your subsequent requests may be held up because of review comments in the + preceding requests. + +- Write a meaningful commit message. Include a meaningful 50 (or less) + character title, followed by a blank line, followed by a more + comprehensive description of the change. Each change MUST include the JIRA + identifier corresponding to the change (e.g. [SPEC-1234]). This can be + in the title but should also be in the body of the commit message. See the [complete requirements](./4_Submitting_Changes.md) for an acceptable change + request. + + **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item. + + ```sh + Bug-AGL: [SPEC-<JIRA-ID>] .... + + Fix [SPEC-<JIRA-ID>] .... + ``` + +Finally, be responsive. Don't let a change request fester with review +comments such that it gets to a point that it requires a rebase. It only +further delays getting it merged and adds more work for you - to +remediate the merge conflicts. + +## Legal stuff + +We have tried to make it as easy as possible to make contributions. This +applies to how we handle the legal aspects of contribution. + +We simply ask that when submitting a patch for review, the developer must +include a sign-off statement in the commit message. + +```sh +Signed-off-by: John Doe <john.doe@example.com> +``` + +You can include this automatically when you commit a change to your +local git repository using ``git commit -s``. diff --git a/docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md b/docs/5_How_To_Contribute/8_Adding_Documentation.md index ed7eb6d..b65e971 100644 --- a/docs/5_How_To_Contribute/1_How_to_add_documentation_to_AGL.md +++ b/docs/5_How_To_Contribute/8_Adding_Documentation.md @@ -2,15 +2,22 @@ title: Adding Documentation --- -The [documentation gerrit repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) contains AGL documentation website template and content, rendering is visible at [https://docs-agl.readthedocs.io/en/latest/](https://docs-agl.readthedocs.io/en/latest/). The documentation site is hosted on [readthedocs](https://readthedocs.org/projects/docs-agl/) and corresponding builds are mentioned [here](https://readthedocs.org/projects/docs-agl/builds/). +The [documentation gerrit repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) +contains AGL documentation website template and content, rendering is +visible at +[https://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/). +The documentation site is hosted on +[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and +corresponding builds are mentioned +[here](https://readthedocs.org/projects/automotivegradelinux/builds/). ## Download Repository -Kindly check [this](https://wiki.automotivelinux.org/agl-distro/contributing) and clone with commit-msg hook : +Clone with commit-msg hook : ```sh -$ git clone "ssh://$USER@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 $USER@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" +$ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" ``` ## Building a local site @@ -71,12 +78,13 @@ documentation ## Test Hyperlinks -[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to check all the hyperlinks in the site. +[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that +allows to check all the hyperlinks in the site. For testing hyperlinks as soon as the local site is running, do: ```sh -linkchecker http://localhost:8000 +$ linkchecker http://localhost:8000 ``` The ```linkchecker``` output will display the broken link and there location @@ -89,25 +97,25 @@ in the site. ```sh #recent version of git-review (>=1.28.0 is required) - sudo pip3 install git-review + $ sudo pip3 install git-review ``` 2. Write commit message ```sh # track all the new changes - git add . + $ git add . # Write the commit message - git commit --signoff + $ git commit --signoff ``` 3. Push changes for review to Gerrit ```sh # first time only - git review -s + $ git review -s # then to push use - git review + $ git review ```
\ No newline at end of file diff --git a/docs/5_How_To_Contribute/images/jira-1.png b/docs/5_How_To_Contribute/images/jira-1.png Binary files differnew file mode 100644 index 0000000..4a39bfb --- /dev/null +++ b/docs/5_How_To_Contribute/images/jira-1.png diff --git a/docs/5_How_To_Contribute/images/jira-2.png b/docs/5_How_To_Contribute/images/jira-2.png Binary files differnew file mode 100644 index 0000000..c1cdb21 --- /dev/null +++ b/docs/5_How_To_Contribute/images/jira-2.png diff --git a/docs/5_How_To_Contribute/images/jira-3.png b/docs/5_How_To_Contribute/images/jira-3.png Binary files differnew file mode 100644 index 0000000..b1bec2e --- /dev/null +++ b/docs/5_How_To_Contribute/images/jira-3.png diff --git a/docs/5_How_To_Contribute/images/review.png b/docs/5_How_To_Contribute/images/review.png Binary files differnew file mode 100644 index 0000000..805166a --- /dev/null +++ b/docs/5_How_To_Contribute/images/review.png |
