diff options
Diffstat (limited to 'docs/06_How_To_Contribute')
| -rw-r--r-- | docs/06_How_To_Contribute/01_Getting_Linux_Foundation_account.md | 98 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/02_Using_Jira_for_current_work_items.md | 30 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/03_Working_with_Gerrit.md | 153 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/04_Submitting_Changes.md | 68 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/05_Reviewing_Changes.md | 55 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/06_Gerrit_Recommended_Practices.md | 263 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/07_General_Guidelines.md | 163 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/08_Adding_Documentation.md | 143 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/09_Contribution_Checklist.md | 60 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/10_Setup_AGL_LAVA_Lab.md | 218 | ||||
| -rw-r--r-- | docs/06_How_To_Contribute/images/jira-1.png | bin | 0 -> 14224 bytes | |||
| -rw-r--r-- | docs/06_How_To_Contribute/images/jira-2.png | bin | 0 -> 74302 bytes | |||
| -rw-r--r-- | docs/06_How_To_Contribute/images/jira-3.png | bin | 0 -> 61399 bytes | |||
| -rw-r--r-- | docs/06_How_To_Contribute/images/review.png | bin | 0 -> 56853 bytes |
14 files changed, 1251 insertions, 0 deletions
diff --git a/docs/06_How_To_Contribute/01_Getting_Linux_Foundation_account.md b/docs/06_How_To_Contribute/01_Getting_Linux_Foundation_account.md new file mode 100644 index 0000000..f2b2cb7 --- /dev/null +++ b/docs/06_How_To_Contribute/01_Getting_Linux_Foundation_account.md @@ -0,0 +1,98 @@ +--- +title: Getting Linux Foundation account +--- + +In order to participate in the development of the Automotive Grade Linux +project, you will need a Linux Foundation account. You will need to use +your LF ID to access to all the AGL community development tools, +including [Gerrit](http://gerrit.automotivelinux.org/), +[Jira](https://jira.automotivelinux.org/) and the +[Wiki](https://wiki.automotivelinux.org/) (for editing, only). + +**NOTE:** Further information about Contributing to the AGL Distro +available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/contributing). + +## Creating Linux Foundation ID + + 1. Go to the [Linux Foundation ID website](https://identity.linuxfoundation.org/). + + 2. Select the option `I need to create a Linux Foundation ID`, and fill + out the form that appears. (It is advised to authenticate through email + instead of logging through Facebook/Google/Github.) + + 3. Wait a few minutes, then look for an email message with the subject + line: `Validate your Linux Foundation ID email`. + + 4. Open the received URL to validate your email address. + + 5. Verify that your browser displays the message ``You have + successfully validated your e-mail address``. + + 6. Access [Gerrit](http://gerrit.automotivelinux.org/) by selecting + ``Sign In``, and use your new Linux Foundation account ID to sign in. + +## Configuring Gerrit to Use SSH + +Gerrit uses SSH to interact with your Git client. If you already have an SSH +key pair, you can skip the part of this section that explains how to generate one. + +What follows explains how to generate an SSH key pair in a Linux environment --- +follow the equivalent steps on your OS. + +First, create an SSH key pair with the command: +**Note:** This guide recommends using ed25519 keys because it has been found that this type works well across all operating systems. + + ```sh + $ ssh-keygen -t ed25519 -C "your_name@example.com" + ``` + +**Note:** When you’re prompted to “Enter a file in which to save the key” press Enter. This accepts the default location. Next, it will ask you for a password to protect the private key as +it generates a unique key. Please keep this password private, and DO NOT +enter a blank password. + +The generated SSH key pair can be found in the files ``~/.ssh/id_ed25519`` and +``~/.ssh/id_ed25519.pub``. + +Next, add the private key in the ``id_ed25519`` file to your key ring, e.g.: + + ```sh + $ ssh-add ~/.ssh/id_ed25519 + ``` + +Finally, add the public key of the generated key pair to the Gerrit +server, with the following steps: + +1. Go to [Gerrit](http://gerrit.automotivelinux.org/). + +2. Click on your account name in the upper right corner. + +3. From the pop-up menu, select ``Settings``. + +4. On the left side menu, click on ``SSH Public Keys``. + +5. Paste the contents of your public key ``~/.ssh/id_ed25519.pub`` and click + ``Add key``. + +**Note:** The ``id_ed25519.pub`` file can be opened with any text editor or you can run the command ``cat ~/.ssh/id_ed25519.pub`` in your terminal and copy output. Ensure that all the contents of the file are selected, copied and pasted into the ``Add SSH key`` window in Gerrit. + +**Note:** The SSH key generation instructions operate on the assumption +that you are using the default naming. It is possible to generate +multiple SSH keys and to name the resulting files differently. See the +[ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) documentation for +details on how to do that. Once you have generated non-default keys, you +need to configure SSH to use the correct key for Gerrit. In that case, +you need to create a ``~/.ssh/config`` file with command ``touch ~/.ssh/config`` and add details in config file. + +``` +host gerrit.automotivelinux.org + HostName gerrit.automotivelinux.org + IdentityFile ~/.ssh/id_ed25519 + User <LFID> + Port 29418 +``` + +`<LFID>` is your Linux Foundation ID(username) and the value of IdentityFile is the +name of the public key file you generated. + +**Warning:** Potential Security Risk! Do not copy your private key +``~/.ssh/id_ed25519``. Use only the public ``~/.ssh/id_ed25519.pub``. diff --git a/docs/06_How_To_Contribute/02_Using_Jira_for_current_work_items.md b/docs/06_How_To_Contribute/02_Using_Jira_for_current_work_items.md new file mode 100644 index 0000000..49b443d --- /dev/null +++ b/docs/06_How_To_Contribute/02_Using_Jira_for_current_work_items.md @@ -0,0 +1,30 @@ +--- +title: Using Jira for current work items +--- + +This document has been created to give further insight into the work in progress +towards the Automotive Grade Linux architecture based on the community roadmap. +The requirements for the roadmap are being tracked in +[Jira](https://jira.automotivelinux.org/). + +On this page you will see all the public (and restricted) boards that have been +created. For example the **Board Name** *CI and Automated Test Expert Group*: + + + +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/06_How_To_Contribute/03_Working_with_Gerrit.md b/docs/06_How_To_Contribute/03_Working_with_Gerrit.md new file mode 100644 index 0000000..e04fe17 --- /dev/null +++ b/docs/06_How_To_Contribute/03_Working_with_Gerrit.md @@ -0,0 +1,153 @@ +--- +title: Working with Gerrit +--- + +Follow these instructions to collaborate on AGL through the Gerrit review +system. + +Please be sure that you are subscribed to the [mailing +list](https://lists.automotivelinux.org/g/agl-dev-community) and of course, you +can reach out on IRC at the #automotive channel on irc.libera.chat + +Gerrit assigns the following roles to users: + +- **Submitters**: May submit changes for consideration, review other code + changes, and make recommendations for acceptance or rejection by voting +1 or + -1, respectively. +- **Maintainers**: May approve or reject changes based upon feedback from + reviewers voting +2 or -2, respectively. + +## Getting deeper into Gerrit + +A comprehensive walk-through of Gerrit is beyond the scope of this document. +There are plenty of resources available on the Internet. A good summary can be +found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and [Basic Gerrit +Walkthrough for GitHub +Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html). + +## Working with a local clone of the repository + +To work on something, whether a new feature or a bugfix: + +1. Open the Gerrit [repo + page](https://gerrit.automotivelinux.org/gerrit/admin/repos/). + +2. Select the repository you wish to work on. + +3. Open a terminal window and clone the project locally using the ``Clone with + git hook`` URL. Be sure that ``ssh`` is also selected, as this will make + authentication much simpler. For example, for `documentation` repository: + + ```sh + $ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P + 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" + ``` + +4. Setup `user` and `email` for git config + + ```sh + $ cd documentation + $ git config --global user.name "Your Full Name" + $ git config --global user.email "your@email.com" + ``` + + **NOTE:** To only configure for a particular repository : + + ```sh + $ cd documentation + $ git config user.name "Your Full Name" + $ git config user.email "your@email.com" + ``` + +5. Create a descriptively-named branch off of your cloned repository + + ```sh + $ git checkout -b issue-nname + ``` + +## Using git review + +There's a **very** useful tool for working with Gerrit called +[git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This +command-line tool can automate most of the ensuing sections for you. Ofcourse, +reading the information below is also highly recommended so that you understand +what's going on behind the scenes. + +```sh +# for first time use only +$ git review -s +``` +If `.gitreview` is missing, add the following section to ``.git/config``, and +replace ``<LFID>`` with your LFID id. + +```sh +[remote "gerrit"] + url = ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation.git + fetch = +refs/heads/*:refs/remotes/gerrit/* +``` + +Then submit your change with ``git review``. + +```sh +$ cd documentation +$ git review +``` + +When you update your patch, you can commit with ``git commit --amend``, and then +repeat the ``git review`` command. + +## Typical Review Workflow + + - New Fresh Change + + ```sh + $ cd documentation # Working Repository + $ git remote -v update # Updating wrt remote + $ git checkout -b mytopicbranch origin/master # Creating new branch + ### CODE the CHANGES + $ git add <file> # Track the changed files + $ git commit -s # Signed Commit Message + $ git review # Submit Changes to review + ``` + + - Updating existing Gerrit Review + + ```sh + $ cd documentation # Working Repository + $ git review -d 25678 # Download review, 25678 is change number + ### CODE the CHANGES + $ git add <file> # Track the changed files + $ git commit -s # Signed Commit Message + $ git review # Submit Changes to review + $ git checkout master # Return to master branch + ``` + +## Reviewing Using Gerrit + +- **Add**: This button allows the change submitter to manually add names of + people who should review a change; start typing a name and the system will + auto-complete based on the list of people registered and with access to the + system. They will be notified by email that you are requesting their input. + +- **Abandon**: This button is available to the submitter only; it allows a + committer to abandon a change and remove it from the merge queue. + +- **Change-ID**: This ID is generated by Gerrit (or system). It becomes useful + when the review process determines that your commit(s) have to be amended. + You may submit a new version; and if the same Change-ID header (and value) + are present, Gerrit will remember it and present it as another version of the + same change. + +- **Status**: Currently, the example change is in review status, as indicated + by “Needs Verified” in the upper-left corner. The list of Reviewers will all + emit their opinion, voting +1 if they agree to the merge, -1 if they + disagree. Gerrit users with a Maintainer role can agree to the merge or + refuse it by voting +2 or -2 respectively. + +Notifications are sent to the email address in your commit message's +Signed-off-by line. Visit your [Gerrit +dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self), to check +the progress of your requests. + +The history tab in Gerrit will show you the in-line comments and the author of +the review. diff --git a/docs/06_How_To_Contribute/04_Submitting_Changes.md b/docs/06_How_To_Contribute/04_Submitting_Changes.md new file mode 100644 index 0000000..871f448 --- /dev/null +++ b/docs/06_How_To_Contribute/04_Submitting_Changes.md @@ -0,0 +1,68 @@ +--- +title: Submitting Changes +--- + +Carefully review the following before submitting a change. These guidelines +apply to developers that are new to open source, as well as to experienced open +source developers. + +## Change Requirements + + +This section contains guidelines for submitting code changes for review. For +more information on how to submit a change using Gerrit, please see [Working +with Gerrit](./03_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/06_How_To_Contribute/05_Reviewing_Changes.md b/docs/06_How_To_Contribute/05_Reviewing_Changes.md new file mode 100644 index 0000000..e9d6758 --- /dev/null +++ b/docs/06_How_To_Contribute/05_Reviewing_Changes.md @@ -0,0 +1,55 @@ +--- +title: Reviewing Changes +--- + +1. Click on a link for incoming or outgoing review. + +2. The details of the change and its current status are loaded: + +  + + - **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/06_How_To_Contribute/06_Gerrit_Recommended_Practices.md b/docs/06_How_To_Contribute/06_Gerrit_Recommended_Practices.md new file mode 100644 index 0000000..671c685 --- /dev/null +++ b/docs/06_How_To_Contribute/06_Gerrit_Recommended_Practices.md @@ -0,0 +1,263 @@ +--- +title: Gerrit Recommended Practices +--- + +This document presents some best practices to help you use Gerrit more +effectively. The intent is to show how content can be submitted easily. Use the +recommended practices to reduce your troubleshooting time and improve +participation in the community. + +## Commit Messages + +Gerrit follows the Git commit message format. Ensure the headers are at the +bottom and don't contain blank lines between one another. The following example +shows the format and content expected in a commit message: + +Brief (no more than 50 chars) one line description. + +Elaborate summary of the changes made referencing why (motivation), what was +changed and how it was tested. Note also any changes to documentation made to +remain consistent with the code changes, wrapping text at 72 chars/line. + +```sh +Bug-AGL: SPEC-<JIRA-ID> + +Change-Id: LONGHEXHASH +Signed-off-by: Your Name your.email\@example.org +``` + +The Gerrit server provides a precommit hook to autogenerate the Change-Id which +is one time use. + +**Recommended reading:** [How to Write a Git Commit +Message](http://chris.beams.io/posts/git-commit/). + +## Avoid Pushing Untested Work to a Gerrit Server + +To avoid pushing untested work to Gerrit. + +Check your work at least three times before pushing your change to Gerrit. Be +mindful of what information you are publishing. + +## Keeping Track of Changes + +- Set Gerrit to send you emails: + +- Gerrit will add you to the email distribution list for a change if a + developer adds you as a reviewer, or if you comment on a specific Patch Set. + +- Opening a change in Gerrit's review interface is a quick way to follow that + change. + +- Watch projects in the Gerrit projects section at ``Gerrit``, select at least + *New Changes, New Patch Sets, All Comments* and *Submitted Changes*. + +Always track the projects you are working on; also see the feedback/comments +[mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn +and help others ramp up. + +## Topic branches + +Topic branches are temporary branches that you push to commit a set of +logically-grouped dependent commits: + +To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed as a +topic in **TopicName** use the following command as an example: + +```sh +$ git push REMOTE HEAD:refs/for/master/TopicName +``` + +The topic will show up in the review ``UI`` and in the ``Open Changes List``. +Topic branches will disappear from the master tree when its content is merged. + +## Finding Available Topics + +```sh +$ ssh -p 29418 <LFID>@gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u +``` + +- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the + current URL where the project is hosted. +- *status* : Indicates the topic's current status: open , merged, abandoned, + draft, merge conflict. +- *project* : Refers to the current name of the project, in this case fabric. +- *branch* : The topic is searched at this branch. +- *topic* : The name of an specific topic, leave it blank to include them all. +- *sort* : Sorts the found topics, in this case by update (-u). + +## Downloading or Checking Out a Change + +In the review UI, on the top right corner, the **Download** link provides a list +of commands and hyperlinks to checkout or download diffs or files. + +We recommend the use of the *git review* plugin. The steps to install git review +are beyond the scope of this document. Refer to the [git review +documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) +for the installation process. + +To check out a specific change using Git, the following command usually works: + +```sh +$ git review -d CHANGEID +``` + +If you don't have Git-review installed, the following commands will do the same +thing: + +```sh +$ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD +``` + +For example, for the 4th version of change 2464, NN is the first two digits +(24): + +```sh +$ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD +``` + +## Using Sandbox Branches + +You can create your own branches to develop features. The branches are pushed to +the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. + +These commands ensure the branch is created in Gerrit's server. + +```sh +$ git checkout -b sandbox/USERNAME/BRANCHNAME +$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME +``` + +Usually, the process to create content is: + +- develop the code, +- break the information into small commits, +- submit changes, +- apply feedback, +- rebase. + +The next command pushes forcibly without review: + +```sh +$ git push REMOTE sandbox/USERNAME/BRANCHNAME +``` + +You can also push forcibly with review: + +```sh +$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME +``` + +## Updating the Version of a Change + +During the review process, you might be asked to update your change. It is +possible to submit multiple versions of the same change. Each version of the +change is called a patch set. + +Always maintain the **Change-Id** that was assigned. For example, there is a +list of commits, **c0...c7**, which were submitted as a topic branch: + +```sh + +$ git log REMOTE/master..master + + c0 + ... + c7 + +$ git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +After you get reviewers' feedback, there are changes in **c3** and **c4** that +must be fixed. If the fix requires rebasing, rebasing changes the commit Ids, +see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section +for more information. However, you must keep the same Change-Id and push the +changes again: + +```sh +$ git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +This new push creates a patches revision, your local history is then cleared. +However you can still access the history of your changes in Gerrit on the +``review UI`` section, for each change. + +It is also permitted to add more commits when pushing new versions. + +### Rebasing + +Rebasing is usually the last step before pushing changes to Gerrit; this allows +you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same. + +- **squash:** mixes two or more commits into a single one. +- **reword:** changes the commit message. +- **edit:** changes the commit content. +- **reorder:** allows you to interchange the order of the commits. +- **rebase:** stacks the commits on top of the master. + +## Rebasing During a Pull + +Before pushing a rebase to your master, ensure that the history has a +consecutive order. + +For example, your ``REMOTE/master`` has the list of commits from **a0** to +**a4**; Then, your changes **c0...c7** are on top of **a4**; thus: + +```sh +$ git log --oneline REMOTE/master..master + + a0 + a1 + a2 + a3 + a4 + c0 + c1 + ... + c7 +``` + +If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a +rebase as follows: + +```sh +$ git pull --rebase REMOTE master +``` + +This pulls **a5-a7** and re-apply **c0-c7** on top of them: + +```sh +$ git log --oneline REMOTE/master..master +a0 +... +a7 +c0 +c1 +... +c7 +``` + +## Getting Better Logs from Git + +Use these commands to change the configuration of Git in order to produce better +logs: + +```sh +$ git config log.abbrevCommit true +``` + +The command above sets the log to abbreviate the commits' hash. + +```sh +$ git config log.abbrev 5 +``` + +The command above sets the abbreviation length to the last 5 characters of the +hash. + +```sh +$ git config format.pretty oneline +``` + +The command above avoids the insertion of an unnecessary line before the Author +line. diff --git a/docs/06_How_To_Contribute/07_General_Guidelines.md b/docs/06_How_To_Contribute/07_General_Guidelines.md new file mode 100644 index 0000000..414e8a9 --- /dev/null +++ b/docs/06_How_To_Contribute/07_General_Guidelines.md @@ -0,0 +1,163 @@ +--- +title: General Guidelines +--- + +## Getting help + +If you are looking for something to work on, or need some expert assistance in +debugging a problem or working out a fix to an issue, our community is always +eager to help. We hang out on various [developer +meetings](https://www.automotivelinux.org/developer-meetings/), IRC (#automotive +on irc.libera.chat) and the [mailing +lists](https://lists.automotivelinux.org/g/agl-dev-community). We will be glad +to help. The only silly question is the one you don't ask. Questions are in fact +a great way to help improve the project as they highlight where our +documentation could be clearer. + +## Reporting bugs + +If you are a user and you have found a bug, please submit an issue using +[JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA issue, +please try to search the existing items to be sure no one else has previously +reported it. If it has been previously reported, then you might add a comment +that you also are interested in seeing the defect fixed. + +If it has not been previously reported, create a new JIRA. Please try to provide +sufficient information for someone else to reproduce the issue. One of the +project's maintainers should respond to your issue within 24 hours. If not, +please bump the issue with a comment and request that it be reviewed. + +## Submitting your fix + +If you just submitted a JIRA for a bug you've discovered, and would like to +provide a fix, we would welcome that gladly! Please assign the JIRA issue to +yourself, then you can submit a change request (CR). + +**NOTE:** If you need help with submitting your first CR, we have created a +brief [tutorial](04_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](04_Submitting_Changes.md) for an acceptable change request. + + **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item. + + ```sh + Bug-AGL: [SPEC-<JIRA-ID>] .... + + Fix [SPEC-<JIRA-ID>] .... + ``` + +Finally, be responsive. Don't let a change request fester with review comments +such that it gets to a point that it requires a rebase. It only further delays +getting it merged and adds more work for you - to remediate the merge conflicts. + +## Legal stuff + +We have tried to make it as easy as possible to make contributions. This applies +to how we handle the legal aspects of contribution. + +We simply ask that when submitting a patch for review, the developer must +include a sign-off statement in the commit message. This is done to ensure that +the author of the change adhere to follow [**DCO**](https://developercertificate.org/). + +```sh +Signed-off-by: John Doe <john.doe@example.com> +``` + +You can include this automatically when you commit a change to your local git +repository using ``git commit -s``. diff --git a/docs/06_How_To_Contribute/08_Adding_Documentation.md b/docs/06_How_To_Contribute/08_Adding_Documentation.md new file mode 100644 index 0000000..4da6165 --- /dev/null +++ b/docs/06_How_To_Contribute/08_Adding_Documentation.md @@ -0,0 +1,143 @@ +--- +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.automotivelinux.org](https://docs.automotivelinux.org). +The documentation site is hosted on +[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and +corresponding builds are mentioned +[here](https://readthedocs.org/projects/automotivegradelinux/builds/). + +## Download Repository + + +Clone with commit-msg hook : + +```sh +$ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" +``` + +## Building a local site + +1. Change into the directory + + ```sh + $ cd documentation + ``` + +2. Install MkDocs and rtd-dropdown theme + + ```sh + $ sudo pip install -r requirements.txt + ``` + +3. If pip is not already installed then install it + ```sh + $ sudo apt-install python3-pip + ``` + + +4. Serve locally (default rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): + + ```sh + $ sudo mkdocs serve + ``` + +Process to **add new or edit existing** markdown files to AGL documentation: + +## Directory Structure + +Find existing or add new markdowns in the following directory structure. + +```sh +documentation +├── docs +│ ├── 1_Getting_Started +│ │ ├── 1_Quickstart +│ │ └── 2_Building_AGL_Image +| ├── ..... +| | +| ├──<Chapter_Number>_<Chapter_Name> +| | ├──<Subchapter_Number>_<Subchapter_Name> +| | | ├──<Index_Number>_<Markdown_Title>.md +| | | ├── ..... +``` +**File Naming convention** AGL follows Snake Case (snake_case) naming convention to name the documentation files. +This type of naming combines words simply by replacing the space with an underscore (_). +All the names will also include a index number before the name. +Index number will use two digit numbers from 01-99 followed by name of the file. +For example: If the file name is Build Process then it will be written as 01_build_process.md + +**Note:** If a file needs to be inserted in between already created sequences, then the index number will be the last index number followed by new numbering. For example, A new file is inserted between 06-07, then the index number for the new file will be 07_01, as in gist sorting, 07_01 will appear after 06 and before 07. + +## Markdown Formatting + + 1. Add following at the start of each markdown : + + ```sh + --- + title: <enter-title> + --- + ``` + + 2. Internal Linking : + + ```sh + [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md) + + + + ``` + +## Test Hyperlinks +[Broken Link Checker](https://github.com/stevenvachon/broken-link-checker) 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 +$ blc http://localhost:8000 -ro +``` + + +For testing hyperlinks of live website do: + +```sh +$ blc https://docs.automotivelinux.org/en/master/ -ro +``` + +The ```Broken Link Checker``` output will display the broken link and there location in +the site. + + +## Submitting changes + +1. Install Git Review + + ```sh + #recent version of git-review (>=1.28.0 is required) + $ sudo pip3 install git-review + ``` + +2. Write commit message (**Note:** Please follow [submitting changes](./04_Submitting_Changes.md) guideline to write your commit message.) + + ```sh + # track all the new changes + $ git add . + + # Write the commit message + $ git commit --signoff + ``` + +3. Push changes for review to Gerrit + + ```sh + # first time only + $ git review -s + + # then to push use + $ git review + ``` diff --git a/docs/06_How_To_Contribute/09_Contribution_Checklist.md b/docs/06_How_To_Contribute/09_Contribution_Checklist.md new file mode 100644 index 0000000..89052e8 --- /dev/null +++ b/docs/06_How_To_Contribute/09_Contribution_Checklist.md @@ -0,0 +1,60 @@ +--- +title: Contribution Checklist +--- + +**Open Source Code Contribution Checklist** + +## General +- [ ] Does the component have a name ? (Pick one fitting the purpose and the project.) +- [ ] Is a separate git repo required for the component ? +- [ ] Does the component have a README.md containing all basic information about it ? + - [ ] Description. + - [ ] Dependencies. + - [ ] Build instructions. + - [ ] Installation instructions. + - [ ] Usage instructions. + - [ ] Example invocations. +- [ ] Does the component have a CONTRIBUTIONS.md file? (Containing all necessary information on how to contribute, e.g. pointing to project website? ) + +## License + - [ ] Is the license an OSI approved open source software license? + - [ ] Are all files under an OSI approved open source license? + - [ ] Does the component have a LICENSE (or COPYING) file detailing the license of the code? + - [ ] Do the source code files have the license mentioned in the header? + - [ ] Do the source code files have an SPDX tag? (Note: An SPDX tag can be used in a file header instead of the license note) + - [ ] Are there files with other licenses in their header? + - [ ] If so, LICENSE should be the for the majority of the files and LICENSE.xyz for the exceptions. + +## docs/ + - [ ] Are there docs/ folder for the component ? + - [ ] e.g. Are all APIs described inclusive description, usage and example invocations ? + - [ ] e.g. Are all cmdline tools or options described in the documentation ? + - [ ] e.g. Is the program flow described ? + - [ ] Contain Changelog.md ? (Keep track of major changes in the changelog.) + +## tests/ + - [ ] Must have tests available. + - [ ] Must have simple invocation scripts available. + - [ ] Must have instructions for CI available. + - [ ] Must contribute CI test definitions. + +## Git repository + - [ ] Must have: a .gitreview file. + - [ ] Option: Can have a .gitignore file. + - [ ] Option: Can have a .editorconfig file. + - [ ] All code needs to build against master. + - [ ] Is a backport to a release branch required ? + - [ ] Code contributions submitted need to have a Sign-off-by! (Follow [**DCO**](https://developercertificate.org/).) + +## Yocto/OE + - [ ] Recipes need to follow the guidelines of : [**new-recipe-writing-a-new-recipe**](https://docs.yoctoproject.org/dev/dev-manual/new-recipe.html#following-recipe-style-guidelines). + - [ ] Recipes follow the [**bitbake style guide**](https://www.openembedded.org/wiki/Styleguide). + - [ ] Your 'meta-*' layer needs to pass the yocto-check-layer tool. + +## Gerrit Reviews +**All gerrit reviews need to be addressed. All issues are to be discussed with the experts.** + + - [ ] Issues are to be discussed in the EG first. + - [ ] Consent needs to be reached. + - [ ] Gerrit commits need two upvotes (not from authors!) to be merged. + - [ ] Uploads should be 'ready for review' or marked 'WIP'. diff --git a/docs/06_How_To_Contribute/10_Setup_AGL_LAVA_Lab.md b/docs/06_How_To_Contribute/10_Setup_AGL_LAVA_Lab.md new file mode 100644 index 0000000..f15545f --- /dev/null +++ b/docs/06_How_To_Contribute/10_Setup_AGL_LAVA_Lab.md @@ -0,0 +1,218 @@ +--- +title: Setting AGL LAVA Lab +--- + +## Overview + +LAVA (Linaro Automated Validation Architecture) Lab is an open source automated testing framework. LAVA is a continuous integration system for deploying operating systems onto physical and virtual hardware for running tests. Tests can be simple boot testing, bootloader testing and system level testing, although extra hardware may be required for some system tests. Results are tracked over time and data can be exported for further analysis. For more information refer [AGL LAVA site](https://lava.automotivelinux.org/) + +## Prerequisites ## + +As well as the packages docker, docker-compose and pyyaml mentioned in the top + +level README, you will need the following: + + + +1) The following ports are forwarded to docker and therefore need to be kept free + +on the host machine: + +- 69/UDP: proxyfied to the slave for TFTP + +- 80: proxyfied to the slave for TODO (transfer overlay) + +- 5500: proxyfied to the slave for Notification + +- 55950-56000: proxyfied to the slave for NBD + +2) You will need a remote power switch to remotely power the DUTs on and off. + +3) You need to have an account with lava.automotivelinux.org. Please contact the + +agl-dev-community mailing list if you would like an account, and include that you would + +like to create your own lab in the email so that the relevant user permissions + +can be set. + + + +## Steps to create your own LAVA lab ## + + + +1) Clone AGL lava-docker image: + +``` + +git clone https://git.automotivelinux.org/AGL/lava-docker.git + +cd lava-docker + +``` + + + +2) On the LAVA master web GUI, create a new API token: + +https://lava.automotivelinux.org/api/tokens/ + + + +3) Connect all the DUTs' serial to usb and ethernet connections to the host. + + +4) Edit the boards.yaml file: + +- Copy the API token you created in step 2 in the place of <generated_lab_token>. + +- Add details of each board connected to the lab. See the top level README for + +instructions. You will need the following: + +- any custom options you require in the kernel args + +- uart idvendor, idproduct, devpath + +- power on, off and reset commads for the power switch + + + +To get the uart idvendor and idproduct, unplug and re-plugin the USB cable of the + +device in question and then find the details in the latest output of: + +``` + +sudo dmesg | grep idvendor + +``` + + + +To get the uart devpath, run the command: + +``` + +udevadm info -a -n /dev/ttyUSB1 |grep devpath | head -n1 + +``` + + + +NOTE: Make sure you have at least one "board" included. (It is easiest to keep + +qemu). + + + +5) Run the automated setup script: + +``` + +./start.sh slave + +``` + + + +7) Check the web GUI to see if the lab has successfully connected to the LAVA + +master: https://lava.automotivelinux.org/scheduler/allworkers. If it isn't, run the + +following command for debugging: + +``` + +docker-exec -it <name_of_docker_container> cat /var/log/lava-dispatcher/lava-slave.log + +``` + +To identify the container name run the following to list the running containers: + +``` + +docker ps + +``` + + + +LAVA logs can be found in `/var/log/lava-dispatcher/`. + + + +8) Helper scripts + +There are a few helper scripts to automate starting/stopping the lab. + +``` + +./start.sh slave + +./restart.sh slave + +./stop.sh slave + +``` + + + +## Adding new device-type templates ## + + + +Not all device types are supported by default. Templates for new devices will + +need to be added to the LAVA master. Please submit new templates to the agl-dev-community + +mailing list. + + + +Before you submit any new device-type templates, please verify that they work. + +You can verify that they work in LAVA by carrying out the following instructions: + +1) Install lavacli on Debian Stretch or Ubuntu 18.04 and later (if you don't + +have a compatible OS, please see https://lava.automotivelinux.org/api/help/ for an + +alternative way to use the API) + +2) Create your lavacli config file + +``` + +touch ~/.config/lavacli.yaml + +``` + +3) Configure this file to look like the following (note: use the first token + +created in https://lava.automotivelinux.org/api/tokens/) + +``` + +default: + +uri: https://lava.automotivelinux.org/RPC2 + +username: <username> + +token: <API_token> + +``` + +4) Add your device template to the master + +``` + +lavacli device-types template set <device-type-name> <device-type-name>.yaml + +``` + +NOTE: make sure your device-type templates always follow the following naming scheme: + +```<device-type-name>.yaml``` diff --git a/docs/06_How_To_Contribute/images/jira-1.png b/docs/06_How_To_Contribute/images/jira-1.png Binary files differnew file mode 100644 index 0000000..4a39bfb --- /dev/null +++ b/docs/06_How_To_Contribute/images/jira-1.png diff --git a/docs/06_How_To_Contribute/images/jira-2.png b/docs/06_How_To_Contribute/images/jira-2.png Binary files differnew file mode 100644 index 0000000..c1cdb21 --- /dev/null +++ b/docs/06_How_To_Contribute/images/jira-2.png diff --git a/docs/06_How_To_Contribute/images/jira-3.png b/docs/06_How_To_Contribute/images/jira-3.png Binary files differnew file mode 100644 index 0000000..b1bec2e --- /dev/null +++ b/docs/06_How_To_Contribute/images/jira-3.png diff --git a/docs/06_How_To_Contribute/images/review.png b/docs/06_How_To_Contribute/images/review.png Binary files differnew file mode 100644 index 0000000..805166a --- /dev/null +++ b/docs/06_How_To_Contribute/images/review.png |
