From f81a7f42d8f10467108bab784117a380e0070ece Mon Sep 17 00:00:00 2001 From: Jan-Simon Moeller Date: Thu, 14 Jan 2021 18:18:25 +0100 Subject: Add a category for agl-compositor and rba documentation Create a home for docs of compositor, rba and pipewire/wireplumber. Also add a .gitignore file. Signed-off-by: Jan-Simon Moeller Change-Id: Id1f9812d0f4db83cb72bf03987dc95d754e00725 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25913 --- docs/5_Component_Documentation/0_AGL_components.md | 14 ++ docs/5_Component_Documentation/1_agl-compositor.md | 7 + .../2_waltham-receiver_waltham-transmitter.md | 7 + docs/5_Component_Documentation/3_rba.md | 7 + .../4_drm-leasemanager.md | 7 + docs/5_Component_Documentation/5_appfw.md | 7 + docs/5_Component_Documentation/6_cynagora.md | 7 + docs/5_Component_Documentation/7_pyagl.md | 7 + .../8_pipewire_wireplumber.md | 7 + .../1_Getting_Linux_Foundation_account.md | 100 -------- .../2_Using_Jira_for_current_work_items.md | 30 --- docs/5_How_To_Contribute/3_Working_with_Gerrit.md | 153 ------------ docs/5_How_To_Contribute/4_Submitting_Changes.md | 68 ------ docs/5_How_To_Contribute/5_Reviewing_Changes.md | 55 ----- .../6_Gerrit_Recommended_Practices.md | 263 --------------------- docs/5_How_To_Contribute/7_General_Guidelines.md | 163 ------------- docs/5_How_To_Contribute/8_Adding_Documentation.md | 121 ---------- .../9_Contribution_Checklist.md | 60 ----- docs/5_How_To_Contribute/images/jira-1.png | Bin 14224 -> 0 bytes docs/5_How_To_Contribute/images/jira-2.png | Bin 74302 -> 0 bytes docs/5_How_To_Contribute/images/jira-3.png | Bin 61399 -> 0 bytes docs/5_How_To_Contribute/images/review.png | Bin 56853 -> 0 bytes .../1_Getting_Linux_Foundation_account.md | 100 ++++++++ .../2_Using_Jira_for_current_work_items.md | 30 +++ docs/6_How_To_Contribute/3_Working_with_Gerrit.md | 153 ++++++++++++ docs/6_How_To_Contribute/4_Submitting_Changes.md | 68 ++++++ docs/6_How_To_Contribute/5_Reviewing_Changes.md | 55 +++++ .../6_Gerrit_Recommended_Practices.md | 263 +++++++++++++++++++++ docs/6_How_To_Contribute/7_General_Guidelines.md | 163 +++++++++++++ docs/6_How_To_Contribute/8_Adding_Documentation.md | 121 ++++++++++ .../9_Contribution_Checklist.md | 60 +++++ docs/6_How_To_Contribute/images/jira-1.png | Bin 0 -> 14224 bytes docs/6_How_To_Contribute/images/jira-2.png | Bin 0 -> 74302 bytes docs/6_How_To_Contribute/images/jira-3.png | Bin 0 -> 61399 bytes docs/6_How_To_Contribute/images/review.png | Bin 0 -> 56853 bytes 35 files changed, 1083 insertions(+), 1013 deletions(-) create mode 100644 docs/5_Component_Documentation/0_AGL_components.md create mode 100644 docs/5_Component_Documentation/1_agl-compositor.md create mode 100644 docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md create mode 100644 docs/5_Component_Documentation/3_rba.md create mode 100644 docs/5_Component_Documentation/4_drm-leasemanager.md create mode 100644 docs/5_Component_Documentation/5_appfw.md create mode 100644 docs/5_Component_Documentation/6_cynagora.md create mode 100644 docs/5_Component_Documentation/7_pyagl.md create mode 100644 docs/5_Component_Documentation/8_pipewire_wireplumber.md delete mode 100644 docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md delete mode 100644 docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md delete mode 100644 docs/5_How_To_Contribute/3_Working_with_Gerrit.md delete mode 100644 docs/5_How_To_Contribute/4_Submitting_Changes.md delete mode 100644 docs/5_How_To_Contribute/5_Reviewing_Changes.md delete mode 100644 docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md delete mode 100644 docs/5_How_To_Contribute/7_General_Guidelines.md delete mode 100644 docs/5_How_To_Contribute/8_Adding_Documentation.md delete mode 100644 docs/5_How_To_Contribute/9_Contribution_Checklist.md delete mode 100644 docs/5_How_To_Contribute/images/jira-1.png delete mode 100644 docs/5_How_To_Contribute/images/jira-2.png delete mode 100644 docs/5_How_To_Contribute/images/jira-3.png delete mode 100644 docs/5_How_To_Contribute/images/review.png create mode 100644 docs/6_How_To_Contribute/1_Getting_Linux_Foundation_account.md create mode 100644 docs/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md create mode 100644 docs/6_How_To_Contribute/3_Working_with_Gerrit.md create mode 100644 docs/6_How_To_Contribute/4_Submitting_Changes.md create mode 100644 docs/6_How_To_Contribute/5_Reviewing_Changes.md create mode 100644 docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md create mode 100644 docs/6_How_To_Contribute/7_General_Guidelines.md create mode 100644 docs/6_How_To_Contribute/8_Adding_Documentation.md create mode 100644 docs/6_How_To_Contribute/9_Contribution_Checklist.md create mode 100644 docs/6_How_To_Contribute/images/jira-1.png create mode 100644 docs/6_How_To_Contribute/images/jira-2.png create mode 100644 docs/6_How_To_Contribute/images/jira-3.png create mode 100644 docs/6_How_To_Contribute/images/review.png (limited to 'docs') diff --git a/docs/5_Component_Documentation/0_AGL_components.md b/docs/5_Component_Documentation/0_AGL_components.md new file mode 100644 index 0000000..d1f5d83 --- /dev/null +++ b/docs/5_Component_Documentation/0_AGL_components.md @@ -0,0 +1,14 @@ +--- +title: AGL Components +--- + +# Components under development within AGL + +- agl-compositor.md +- waltham-receiver_waltham-transmitter.md +- rba.md +- drm-leasemanager.md +- appfw.md +- cynagora.md +- pyagl.md +- pipewire_wireplumber.md diff --git a/docs/5_Component_Documentation/1_agl-compositor.md b/docs/5_Component_Documentation/1_agl-compositor.md new file mode 100644 index 0000000..892a48f --- /dev/null +++ b/docs/5_Component_Documentation/1_agl-compositor.md @@ -0,0 +1,7 @@ +--- +title: agl-compositor +--- + +# agl-compositor + +FIXME. diff --git a/docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md b/docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md new file mode 100644 index 0000000..cfaaf7b --- /dev/null +++ b/docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md @@ -0,0 +1,7 @@ +--- +title: Waltham receiver/transmitter +--- + +# waltham + +FIXME. diff --git a/docs/5_Component_Documentation/3_rba.md b/docs/5_Component_Documentation/3_rba.md new file mode 100644 index 0000000..340d4b1 --- /dev/null +++ b/docs/5_Component_Documentation/3_rba.md @@ -0,0 +1,7 @@ +--- +title: Rule Based Arbitrator (rba) +--- + +# rba + +FIXME. diff --git a/docs/5_Component_Documentation/4_drm-leasemanager.md b/docs/5_Component_Documentation/4_drm-leasemanager.md new file mode 100644 index 0000000..30f86cc --- /dev/null +++ b/docs/5_Component_Documentation/4_drm-leasemanager.md @@ -0,0 +1,7 @@ +--- +title: DRM lease manager +--- + +# DRM lease manager + +FIXME. diff --git a/docs/5_Component_Documentation/5_appfw.md b/docs/5_Component_Documentation/5_appfw.md new file mode 100644 index 0000000..1af8796 --- /dev/null +++ b/docs/5_Component_Documentation/5_appfw.md @@ -0,0 +1,7 @@ +--- +title: Application Framework +--- + +# AppFW + +FIXME. diff --git a/docs/5_Component_Documentation/6_cynagora.md b/docs/5_Component_Documentation/6_cynagora.md new file mode 100644 index 0000000..d2c74ce --- /dev/null +++ b/docs/5_Component_Documentation/6_cynagora.md @@ -0,0 +1,7 @@ +--- +title: Cynagora +--- + +# cynagora + +FIXME. diff --git a/docs/5_Component_Documentation/7_pyagl.md b/docs/5_Component_Documentation/7_pyagl.md new file mode 100644 index 0000000..6de0a07 --- /dev/null +++ b/docs/5_Component_Documentation/7_pyagl.md @@ -0,0 +1,7 @@ +--- +title: PyAGL +--- + +# PyAGL + +FIXME. diff --git a/docs/5_Component_Documentation/8_pipewire_wireplumber.md b/docs/5_Component_Documentation/8_pipewire_wireplumber.md new file mode 100644 index 0000000..d5ca335 --- /dev/null +++ b/docs/5_Component_Documentation/8_pipewire_wireplumber.md @@ -0,0 +1,7 @@ +--- +title: Pipewire / Wireplumber +--- + +# Pipewire / Wireplumber + +FIXME. 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 deleted file mode 100644 index c4d8b08..0000000 --- a/docs/5_How_To_Contribute/1_Getting_Linux_Foundation_account.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -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 -``` - -`` 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 deleted file mode 100644 index 49b443d..0000000 --- a/docs/5_How_To_Contribute/2_Using_Jira_for_current_work_items.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Using Jira for current work items ---- - -This document has been created to give further insight into the work in progress -towards the Automotive Grade Linux architecture based on the community roadmap. -The requirements for the roadmap are being tracked in -[Jira](https://jira.automotivelinux.org/). - -On this page you will see all the public (and restricted) boards that have been -created. For example the **Board Name** *CI and Automated Test Expert Group*: - -![Jira boards](images/jira-2.png) - -When you click on *CI and Automated Test Expert Group* under **Board name** you -will be directed to a page that contains the following columns: - -![Jira boards](images/jira-3.png) - -The meanings to these columns are as follows: - -- **NOT STARTED** – list of items slated for the current sprint (sprints are - defined in 2 week iterations), but are not currently in progress -- **IN PROGRESS** – items currently being worked by someone in the community. -- **DONE** – items merged and complete in the sprint. - -If there is an item you are interested in working on, want more information or -have questions, or if there is an item that you feel needs to be in higher -priority, please add comments directly to the Jira item. All feedback and help -is very much appreciated. \ No newline at end of file diff --git a/docs/5_How_To_Contribute/3_Working_with_Gerrit.md b/docs/5_How_To_Contribute/3_Working_with_Gerrit.md deleted file mode 100644 index 44da2d9..0000000 --- a/docs/5_How_To_Contribute/3_Working_with_Gerrit.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -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://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P - 29418 @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 ```` with your LFID id. - -```sh -[remote "gerrit"] - url = ssh://@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  # 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  # 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 deleted file mode 100644 index d226450..0000000 --- a/docs/5_How_To_Contribute/4_Submitting_Changes.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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-] -Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 -Signed-off-by: Your Name -``` - -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 -``` - -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 deleted file mode 100644 index e9d6758..0000000 --- a/docs/5_How_To_Contribute/5_Reviewing_Changes.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Reviewing Changes ---- - -1. Click on a link for incoming or outgoing review. - -2. The details of the change and its current status are loaded: - - ![review](images/review.png) - - - **Status:** Displays the current status of the change. - - - **Reply:** Click on this button after reviewing to add a final review - message and a score, -1, 0 or +1. - - - **Patch Sets:** If multiple revisions of a patch exist, this button - enables navigation among revisions to see the changes. By default, the - most recent revision is presented. - - - **Download:** This button brings up another window with multiple - options to download or checkout the current changeset. The button on - the right copies the line to your clipboard. You can easily paste it - into your git interface to work with the patch as you prefer. - - Underneath the commit information, the files that have been changed by - this patch are displayed. - -3. Click on a filename to review it. Select the code base to differentiate - against. The default is ``Base`` and it will generally be what is needed. - -4. The review page presents the changes made to the file. At the top of the - review, the presentation shows some general navigation options. Navigate - through the patch set using the arrows on the top right corner. It is - possible to go to the previous or next file in the set or to return to the - main change screen. Click on the yellow sticky pad to add comments to the - whole file. - - The focus of the page is on the comparison window. The changes made are - presented in green on the right versus the base version on the left. - Double click to highlight the text within the actual change to provide - feedback on a specific section of the code. Press *c* once the code is - highlighted to add comments to that section. - -5. After adding the comment, it is saved as a *Draft*. - -6. Once you have reviewed all files and provided feedback, click the *green up - arrow* at the top right to return to the main change page. Click the - ``Reply`` button, write some final comments, and submit your score for the - patch set. Click ``Post`` to submit the review of each reviewed file, as well - as your final comment and score. Gerrit sends an email to the - change-submitter and all listed reviewers. Finally, it logs the review for - future reference. All individual comments are saved as *Draft* until the - ``Post`` button is clicked. - - diff --git a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md deleted file mode 100644 index 671c685..0000000 --- a/docs/5_How_To_Contribute/6_Gerrit_Recommended_Practices.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -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- - -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 @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 deleted file mode 100644 index b72e912..0000000 --- a/docs/5_How_To_Contribute/7_General_Guidelines.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -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-] .... - - Fix [SPEC-] .... - ``` - -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 -``` - -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 deleted file mode 100644 index d2aad82..0000000 --- a/docs/5_How_To_Contribute/8_Adding_Documentation.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Adding Documentation ---- - -The [documentation gerrit -repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) -contains AGL documentation website template and content, rendering is visible at -[https://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/). -The documentation site is hosted on -[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and -corresponding builds are mentioned -[here](https://readthedocs.org/projects/automotivegradelinux/builds/). - -## Download Repository - - -Clone with commit-msg hook : - -```sh -$ git clone "ssh://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 @gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" -``` - -## Building a local site - -1. Change into the directory - - ```sh - $ cd documentation - ``` - -2. Install MkDocs and rtd-dropdown theme - - ```sh - $ sudo pip install -r requirements.txt - ``` - -3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): - - ```sh - $ sudo mkdocs serve - ``` - -Process to **add new or edit existing** markdown files to AGL documentation: - -## Directory Structure - -Find existing or add new markdowns in the following directory structure. - -```sh -documentation -├── docs -│   ├── 0_Getting_Started -│   │   ├── 1_Quickstart -│   │   └── 2_Building_AGL_Image -| ├── ..... -| | -| ├──_ -| | ├──_ -| | | ├──_.md -| | | ├── ..... -``` - -## Markdown Formatting - - 1. Add following at the start of each markdown : - - ```sh - --- - title: - --- - ``` - - 2. Internal Linking : - - ```sh - [](../_/_/_.md) - ``` - -## Test Hyperlinks - -[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to -check all the hyperlinks in the site. - -For testing hyperlinks as soon as the local site is running, do: - -```sh -$ linkchecker http://localhost:8000 -``` - -The ```linkchecker``` output will display the broken link and there location in -the site. - - -## Submitting changes - -1. Install Git Review - - ```sh - #recent version of git-review  (>=1.28.0 is required) - $ sudo pip3 install git-review  - ``` - -2. Write commit message - - ```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 - ``` \ No newline at end of file diff --git a/docs/5_How_To_Contribute/9_Contribution_Checklist.md b/docs/5_How_To_Contribute/9_Contribution_Checklist.md deleted file mode 100644 index 7d86ada..0000000 --- a/docs/5_How_To_Contribute/9_Contribution_Checklist.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Contribution Checklist ---- - -**Open Source Code Contribution Checklist** - -## General -- [ ] Does the component have a name ? (Pick one fitting the purpose and the project.) -- [ ] Is a separate git repo required for the component ? -- [ ] Does the component have a README.md containing all basic information about it ? - - [ ] Description. - - [ ] Dependencies. - - [ ] Build instructions. - - [ ] Installation instructions. - - [ ] Usage instructions. - - [ ] Example invocations. -- [ ] Does the component have a CONTRIBUTIONS.md file? (Containing all necessary information on how to contribute, e.g. pointing to project website? ) - -## License - - [ ] Is the license an OSI approved open source software license? - - [ ] Are all files under an OSI approved open source license? - - [ ] Does the component have a LICENSE (or COPYING) file detailing the license of the code? - - [ ] Do the source code files have the license mentioned in the header? - - [ ] Do the source code files have an SPDX tag? (Note: An SPDX tag can be used in a file header instead of the license note) - - [ ] Are there files with other licenses in their header? - - [ ] If so, LICENSE should be the for the majority of the files and LICENSE.xyz for the exceptions. - -## docs/ - - [ ] Are there docs/ folder for the component ? - - [ ] e.g. Are all APIs described inclusive description, usage and example invocations ? - - [ ] e.g. Are all cmdline tools or options described in the documentation ? - - [ ] e.g. Is the program flow described ? - - [ ] Contain Changelog.md ? (Keep track of major changes in the changelog.) - -## tests/ - - [ ] Must have tests available. - - [ ] Must have simple invocation scripts available. - - [ ] Must have instructions for CI available. - - [ ] Must contribute CI test definitions. - -## Git repository - - [ ] Must have: a .gitreview file. - - [ ] Option: Can have a .gitignore file. - - [ ] Option: Can have a .editorconfig file. - - [ ] All code needs to build against master. - - [ ] Is a backport to a release branch required ? - - [ ] Code contributions submitted need to have a Sign-off-by! (Follow [**DCO**](https://developercertificate.org/).) - -## Yocto/OE - - [ ] Recipes need to follow the guidelines of : [**new-recipe-writing-a-new-recipe**](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#new-recipe-writing-a-new-recipe). - - [ ] Recipes follow the [**bitbake style guide**](https://www.openembedded.org/wiki/Styleguide). - - [ ] Your 'meta-*' layer needs to pass the yocto-check-layer tool. - -## Gerrit Reviews -**All gerrit reviews need to be addressed. All issues are to be discussed with the experts.** - - - [ ] Issues are to be discussed in the EG first. - - [ ] Consent needs to be reached. - - [ ] Gerrit commits need two upvotes (not from authors!) to be merged. - - [ ] Uploads should be 'ready for review' or marked 'WIP'. \ No newline at end of file diff --git a/docs/5_How_To_Contribute/images/jira-1.png b/docs/5_How_To_Contribute/images/jira-1.png deleted file mode 100644 index 4a39bfb..0000000 Binary files a/docs/5_How_To_Contribute/images/jira-1.png and /dev/null differ diff --git a/docs/5_How_To_Contribute/images/jira-2.png b/docs/5_How_To_Contribute/images/jira-2.png deleted file mode 100644 index c1cdb21..0000000 Binary files a/docs/5_How_To_Contribute/images/jira-2.png and /dev/null differ diff --git a/docs/5_How_To_Contribute/images/jira-3.png b/docs/5_How_To_Contribute/images/jira-3.png deleted file mode 100644 index b1bec2e..0000000 Binary files a/docs/5_How_To_Contribute/images/jira-3.png and /dev/null differ diff --git a/docs/5_How_To_Contribute/images/review.png b/docs/5_How_To_Contribute/images/review.png deleted file mode 100644 index 805166a..0000000 Binary files a/docs/5_How_To_Contribute/images/review.png and /dev/null differ diff --git a/docs/6_How_To_Contribute/1_Getting_Linux_Foundation_account.md b/docs/6_How_To_Contribute/1_Getting_Linux_Foundation_account.md new file mode 100644 index 0000000..c4d8b08 --- /dev/null +++ b/docs/6_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 +``` + +`` 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/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md b/docs/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md new file mode 100644 index 0000000..49b443d --- /dev/null +++ b/docs/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md @@ -0,0 +1,30 @@ +--- +title: Using Jira for current work items +--- + +This document has been created to give further insight into the work in progress +towards the Automotive Grade Linux architecture based on the community roadmap. +The requirements for the roadmap are being tracked in +[Jira](https://jira.automotivelinux.org/). + +On this page you will see all the public (and restricted) boards that have been +created. For example the **Board Name** *CI and Automated Test Expert Group*: + +![Jira boards](images/jira-2.png) + +When you click on *CI and Automated Test Expert Group* under **Board name** you +will be directed to a page that contains the following columns: + +![Jira boards](images/jira-3.png) + +The meanings to these columns are as follows: + +- **NOT STARTED** – list of items slated for the current sprint (sprints are + defined in 2 week iterations), but are not currently in progress +- **IN PROGRESS** – items currently being worked by someone in the community. +- **DONE** – items merged and complete in the sprint. + +If there is an item you are interested in working on, want more information or +have questions, or if there is an item that you feel needs to be in higher +priority, please add comments directly to the Jira item. All feedback and help +is very much appreciated. \ No newline at end of file diff --git a/docs/6_How_To_Contribute/3_Working_with_Gerrit.md b/docs/6_How_To_Contribute/3_Working_with_Gerrit.md new file mode 100644 index 0000000..44da2d9 --- /dev/null +++ b/docs/6_How_To_Contribute/3_Working_with_Gerrit.md @@ -0,0 +1,153 @@ +--- +title: Working with Gerrit +--- + +Follow these instructions to collaborate on AGL through the Gerrit review +system. + +Please be sure that you are subscribed to the [mailing +list](https://lists.automotivelinux.org/g/agl-dev-community) and of course, you +can reach out on IRC at the #automotive channel on 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://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P + 29418 @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 ```` with your LFID id. + +```sh +[remote "gerrit"] + url = ssh://@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  # 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  # 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/6_How_To_Contribute/4_Submitting_Changes.md b/docs/6_How_To_Contribute/4_Submitting_Changes.md new file mode 100644 index 0000000..d226450 --- /dev/null +++ b/docs/6_How_To_Contribute/4_Submitting_Changes.md @@ -0,0 +1,68 @@ +--- +title: Submitting Changes +--- + +Carefully review the following before submitting a change. These guidelines +apply to developers that are new to open source, as well as to experienced open +source developers. + +## Change Requirements + + +This section contains guidelines for submitting code changes for review. For +more information on how to submit a change using Gerrit, please see [Working +with Gerrit](./3_Working_with_Gerrit.md). + +Changes are submitted as Git commits. Each commit must contain: + +- a short and descriptive subject line that is 72 characters or fewer, followed + by a blank line. +- a change description with your logic or reasoning for the changes, followed + by a blank line +- a Signed-off-by line, followed by a colon (Signed-off-by:) +- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit won't + accept patches without this identifier. + +A commit with the above details is considered well-formed. [This +page](https://chris.beams.io/posts/git-commit/) is a very useful for the same. + +All changes and topics sent to Gerrit must be well-formed. Informationally, +``commit messages`` must include: + +- **what** the change does, +- **why** you chose that approach, and +- **how** you know it works -- for example, which tests you ran. + +For example: One commit fixes whitespace issues, another renames a function and +a third one changes the code's functionality. An example commit file is +illustrated below in detail: + +```sh + +A short description of your change with no period at the end + +You can add more details here in several paragraphs, but please keep each line +width less than 80 characters. A bug fix should include the issue number. + +Bug-AGL: [SPEC-] +Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 +Signed-off-by: Your Name +``` + +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 +``` + +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/6_How_To_Contribute/5_Reviewing_Changes.md b/docs/6_How_To_Contribute/5_Reviewing_Changes.md new file mode 100644 index 0000000..e9d6758 --- /dev/null +++ b/docs/6_How_To_Contribute/5_Reviewing_Changes.md @@ -0,0 +1,55 @@ +--- +title: Reviewing Changes +--- + +1. Click on a link for incoming or outgoing review. + +2. The details of the change and its current status are loaded: + + ![review](images/review.png) + + - **Status:** Displays the current status of the change. + + - **Reply:** Click on this button after reviewing to add a final review + message and a score, -1, 0 or +1. + + - **Patch Sets:** If multiple revisions of a patch exist, this button + enables navigation among revisions to see the changes. By default, the + most recent revision is presented. + + - **Download:** This button brings up another window with multiple + options to download or checkout the current changeset. The button on + the right copies the line to your clipboard. You can easily paste it + into your git interface to work with the patch as you prefer. + + Underneath the commit information, the files that have been changed by + this patch are displayed. + +3. Click on a filename to review it. Select the code base to differentiate + against. The default is ``Base`` and it will generally be what is needed. + +4. The review page presents the changes made to the file. At the top of the + review, the presentation shows some general navigation options. Navigate + through the patch set using the arrows on the top right corner. It is + possible to go to the previous or next file in the set or to return to the + main change screen. Click on the yellow sticky pad to add comments to the + whole file. + + The focus of the page is on the comparison window. The changes made are + presented in green on the right versus the base version on the left. + Double click to highlight the text within the actual change to provide + feedback on a specific section of the code. Press *c* once the code is + highlighted to add comments to that section. + +5. After adding the comment, it is saved as a *Draft*. + +6. Once you have reviewed all files and provided feedback, click the *green up + arrow* at the top right to return to the main change page. Click the + ``Reply`` button, write some final comments, and submit your score for the + patch set. Click ``Post`` to submit the review of each reviewed file, as well + as your final comment and score. Gerrit sends an email to the + change-submitter and all listed reviewers. Finally, it logs the review for + future reference. All individual comments are saved as *Draft* until the + ``Post`` button is clicked. + + diff --git a/docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md new file mode 100644 index 0000000..671c685 --- /dev/null +++ b/docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md @@ -0,0 +1,263 @@ +--- +title: Gerrit Recommended Practices +--- + +This document presents some best practices to help you use Gerrit more +effectively. The intent is to show how content can be submitted easily. Use the +recommended practices to reduce your troubleshooting time and improve +participation in the community. + +## Commit Messages + +Gerrit follows the Git commit message format. Ensure the headers are at the +bottom and don't contain blank lines between one another. The following example +shows the format and content expected in a commit message: + +Brief (no more than 50 chars) one line description. + +Elaborate summary of the changes made referencing why (motivation), what was +changed and how it was tested. Note also any changes to documentation made to +remain consistent with the code changes, wrapping text at 72 chars/line. + +```sh +Bug-AGL: SPEC- + +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 @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/6_How_To_Contribute/7_General_Guidelines.md b/docs/6_How_To_Contribute/7_General_Guidelines.md new file mode 100644 index 0000000..b72e912 --- /dev/null +++ b/docs/6_How_To_Contribute/7_General_Guidelines.md @@ -0,0 +1,163 @@ +--- +title: General Guidelines +--- + +## Getting help + +If you are looking for something to work on, or need some expert assistance in +debugging a problem or working out a fix to an issue, our community is always +eager to help. We hang out on various [developer +meetings](https://www.automotivelinux.org/developer-meetings/), IRC (#automotive +on 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-] .... + + Fix [SPEC-] .... + ``` + +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 +``` + +You can include this automatically when you commit a change to your local git +repository using ``git commit -s``. diff --git a/docs/6_How_To_Contribute/8_Adding_Documentation.md b/docs/6_How_To_Contribute/8_Adding_Documentation.md new file mode 100644 index 0000000..d2aad82 --- /dev/null +++ b/docs/6_How_To_Contribute/8_Adding_Documentation.md @@ -0,0 +1,121 @@ +--- +title: Adding Documentation +--- + +The [documentation gerrit +repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) +contains AGL documentation website template and content, rendering is visible at +[https://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/). +The documentation site is hosted on +[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and +corresponding builds are mentioned +[here](https://readthedocs.org/projects/automotivegradelinux/builds/). + +## Download Repository + + +Clone with commit-msg hook : + +```sh +$ git clone "ssh://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 @gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" +``` + +## Building a local site + +1. Change into the directory + + ```sh + $ cd documentation + ``` + +2. Install MkDocs and rtd-dropdown theme + + ```sh + $ sudo pip install -r requirements.txt + ``` + +3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): + + ```sh + $ sudo mkdocs serve + ``` + +Process to **add new or edit existing** markdown files to AGL documentation: + +## Directory Structure + +Find existing or add new markdowns in the following directory structure. + +```sh +documentation +├── docs +│   ├── 0_Getting_Started +│   │   ├── 1_Quickstart +│   │   └── 2_Building_AGL_Image +| ├── ..... +| | +| ├──_ +| | ├──_ +| | | ├──_.md +| | | ├── ..... +``` + +## Markdown Formatting + + 1. Add following at the start of each markdown : + + ```sh + --- + title: + --- + ``` + + 2. Internal Linking : + + ```sh + [](../_/_/_.md) + ``` + +## Test Hyperlinks + +[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to +check all the hyperlinks in the site. + +For testing hyperlinks as soon as the local site is running, do: + +```sh +$ linkchecker http://localhost:8000 +``` + +The ```linkchecker``` output will display the broken link and there location in +the site. + + +## Submitting changes + +1. Install Git Review + + ```sh + #recent version of git-review  (>=1.28.0 is required) + $ sudo pip3 install git-review  + ``` + +2. Write commit message + + ```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 + ``` \ No newline at end of file diff --git a/docs/6_How_To_Contribute/9_Contribution_Checklist.md b/docs/6_How_To_Contribute/9_Contribution_Checklist.md new file mode 100644 index 0000000..7d86ada --- /dev/null +++ b/docs/6_How_To_Contribute/9_Contribution_Checklist.md @@ -0,0 +1,60 @@ +--- +title: Contribution Checklist +--- + +**Open Source Code Contribution Checklist** + +## General +- [ ] Does the component have a name ? (Pick one fitting the purpose and the project.) +- [ ] Is a separate git repo required for the component ? +- [ ] Does the component have a README.md containing all basic information about it ? + - [ ] Description. + - [ ] Dependencies. + - [ ] Build instructions. + - [ ] Installation instructions. + - [ ] Usage instructions. + - [ ] Example invocations. +- [ ] Does the component have a CONTRIBUTIONS.md file? (Containing all necessary information on how to contribute, e.g. pointing to project website? ) + +## License + - [ ] Is the license an OSI approved open source software license? + - [ ] Are all files under an OSI approved open source license? + - [ ] Does the component have a LICENSE (or COPYING) file detailing the license of the code? + - [ ] Do the source code files have the license mentioned in the header? + - [ ] Do the source code files have an SPDX tag? (Note: An SPDX tag can be used in a file header instead of the license note) + - [ ] Are there files with other licenses in their header? + - [ ] If so, LICENSE should be the for the majority of the files and LICENSE.xyz for the exceptions. + +## docs/ + - [ ] Are there docs/ folder for the component ? + - [ ] e.g. Are all APIs described inclusive description, usage and example invocations ? + - [ ] e.g. Are all cmdline tools or options described in the documentation ? + - [ ] e.g. Is the program flow described ? + - [ ] Contain Changelog.md ? (Keep track of major changes in the changelog.) + +## tests/ + - [ ] Must have tests available. + - [ ] Must have simple invocation scripts available. + - [ ] Must have instructions for CI available. + - [ ] Must contribute CI test definitions. + +## Git repository + - [ ] Must have: a .gitreview file. + - [ ] Option: Can have a .gitignore file. + - [ ] Option: Can have a .editorconfig file. + - [ ] All code needs to build against master. + - [ ] Is a backport to a release branch required ? + - [ ] Code contributions submitted need to have a Sign-off-by! (Follow [**DCO**](https://developercertificate.org/).) + +## Yocto/OE + - [ ] Recipes need to follow the guidelines of : [**new-recipe-writing-a-new-recipe**](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#new-recipe-writing-a-new-recipe). + - [ ] Recipes follow the [**bitbake style guide**](https://www.openembedded.org/wiki/Styleguide). + - [ ] Your 'meta-*' layer needs to pass the yocto-check-layer tool. + +## Gerrit Reviews +**All gerrit reviews need to be addressed. All issues are to be discussed with the experts.** + + - [ ] Issues are to be discussed in the EG first. + - [ ] Consent needs to be reached. + - [ ] Gerrit commits need two upvotes (not from authors!) to be merged. + - [ ] Uploads should be 'ready for review' or marked 'WIP'. \ No newline at end of file diff --git a/docs/6_How_To_Contribute/images/jira-1.png b/docs/6_How_To_Contribute/images/jira-1.png new file mode 100644 index 0000000..4a39bfb Binary files /dev/null and b/docs/6_How_To_Contribute/images/jira-1.png differ diff --git a/docs/6_How_To_Contribute/images/jira-2.png b/docs/6_How_To_Contribute/images/jira-2.png new file mode 100644 index 0000000..c1cdb21 Binary files /dev/null and b/docs/6_How_To_Contribute/images/jira-2.png differ diff --git a/docs/6_How_To_Contribute/images/jira-3.png b/docs/6_How_To_Contribute/images/jira-3.png new file mode 100644 index 0000000..b1bec2e Binary files /dev/null and b/docs/6_How_To_Contribute/images/jira-3.png differ diff --git a/docs/6_How_To_Contribute/images/review.png b/docs/6_How_To_Contribute/images/review.png new file mode 100644 index 0000000..805166a Binary files /dev/null and b/docs/6_How_To_Contribute/images/review.png differ -- cgit 1.2.3-korg