Contributor Guidelines

Thanks for helping to improve AGL ! This page provides a general guide on making contributions to AGL. If you can’t find something on this page, please feel free to contact the mailing list.

Prerequisites

Before contributing to AGL, please complete the following steps:

  1. Create an account on identity.linuxfoundation.org to get started.
  2. Join the mailing list.
  3. Setup your Gerrit account, as described in the Gerrit Tutorial from mediawiki

Working with JIRA

Issues for AGL are hosted in the AGL JIRA server. When reporting issues, please follow these guidelines.

Claiming Issues

If you find a JIRA issue that you would like to work on, you can ask to claim it; please leave a comment indicating your intention and a committer will assign it to you. Some issues in JIRA are auto-assigned to certain contributors. If it is clear that an issue is not being worked on, feel free to work on it yourself (but please comment first to let the asignee know).

Submitting Code

Access Control

Access control to gerrit is defined in this google doc spreadsheet

Gerrit Roles

The overall Gerrit workflow for a code change submitted to the project follows this diagram.

Gerrit roles

One can assume that requesting changes to be reverted will follow the same flow as those for new code and patches. Access to various functions within gerrit is granted according the roles defined here.

AGL Committer

The most general role in the project is the AGL-committer. They may push proposed changes to gerrit, initiate a code review of those changes, and perform code reviews of proposed changes.

AGL Committer

AGL Mergers

The ability to accept and merge changes into the AGL Repositories is reserved for role of AGL-mergers. AGL-mergers have all access granted to AGL-committers as well as the ability to +2 or -2 any proposed changes and submit those changes to the AGL Repository in gerrit. Self-review by AGL Mergers is generally frowned upon and AGL-mergers should only give a +2 or -2 after others reviewers after weighed in on the change.

AGL Mergers

General Access

Registered users in gerrit without any of the above access levels may fetch the repositories or may participate in reviews. This allows registered users to be added to reviews by committers without having to be added to the Committer list.

Gerrit Access


Patch Review and Merge Policy

In addition to providing comments and suggestions for improvement, reviewers are encouraged to respond to changes with an overall +1, -1 type value. The meaning of these numbers is explained in the https://gerrit.baserock.org/Documentation/config-labels.html#label_Code-Review

Here is a brief summary of the values:

-2: This must not be merged.
-1: I would prefer that this is not merged as is.
0: I am not making any statement about this change at the moment.
+1: Looks good to me, but someone else must approve it.
+2: Looks good to me, approved.

These values do not get added together by Gerrit, so two +1s do not lead to an automatic merge.

Changes can only be merged to the master branch once they have received a +2 and no -2. Only members of the AGL-Mergers group can give +2.


Gerrit Use Cases

Actors

Repositories

Prepare to push changes in Gerrit

By default the repo tool will have clone git repo with http for fetch and ssh to push. #cd meta-agl #git remote -v agl https://gerrit.automotivelinux.org/gerrit/AGL/meta-agl (fetch) agl ssh://gerrit.automotivelinux.org:29418/AGL/meta-agl (push)

if you want to use your ssh config, add your gerrit user accout to your ssh config file like: #cat ~/.ssh/config Host gerrit.automotivelinux.org User XXXMyNameXXX

Then you still need to enter you ssh public key in Gerrit. You can find a HowTo [[ https://www.mediawiki.org/wiki/Gerrit/Tutorial#Set_Up_SSH_Keys_in_Gerrit here ]]

Push changes for review to Gerrit

Git Commit Messages

You are highly encouraged to describe your git commit with enough detail for someone else to understand it. In doing so, your commit message can consist of multiple lines. However, it also is highly encouraged that the first line of your commit message not exceed 50 characters. This is because some of the tooling that sits on top of git (such as the httpd apps that let you browse the repos) assumes that the first line is top-level summary that is 50 characters or less. Thus there will be highlighting and truncating of the commit message using these assumptions and it will look weird if these assumptions are not kept. There should also be a blank line between the summary and any further description.

If the commit is related to a JIRA issue, you can specify ‘Bug-AGL: ‘ followed by the issue number.

For example, here is a good commit message:

Fixed the whizbang widget

Bug-AGL: SPEC-0000

- added more sanity checking in the build script.
- fixed the API to return the correct value in the scenario where there
  aren't any whizbangs present.
- corrected the documentation.

As an alternate to a bullet list, you could put long text here in paragraph form, with each line wrapped at 72 chars and blank lines between paragraphs.

Please sign you commit before you submit the change (otherwise it will not be accepted by gerrit): git commit –signoff

git push agl HEAD:refs/for/master git push HEAD:refs/for/

# first time only git review -s

# then to push use git review

Find more details in these guides:

Personal Sandbox Projects in Gerrit

First time:

   meta-agl> git push gerrit testsandbox:refs/heads/sandbox/jsmoeller/test
  Total 0 (delta 0), reused 0 (delta 0)
  remote: Processing changes: closed: 114, refs: 1, done
  To ssh://jsmoeller@gerrit.automotivelinux.org:29418/AGL/meta-agl
   * [new branch]      testsandbox -> sandbox/jsmoeller/test''

Push to personal branch:

  git push gerrit testsandbox:refs/for/sandbox/jsmoeller/test
  Counting objects: 2, Fertig.
  Delta compression using up to 8 threads.
  Compressing: 100% (2/2), Fertig.
  Writing objects: 100% (2/2), 327 bytes | 0 bytes/s, Fertig.
  Total 2 (delta 1), reused 0 (delta 0)
  remote: Resolving deltas: 100% (1/1)
  remote: Processing changes: new: 1, refs: 1, done
  remote:
  remote: New Changes:
  remote:   https://gerrit.automotivelinux.org/gerrit/5643 test1
  remote:
  To ssh://jsmoeller@gerrit.automotivelinux.org:29418/AGL/meta-agl
   * [new branch]      testsandbox -> refs/for/sandbox/jsmoeller/test


Notes on Use Cases

* In this context a subsystem is part of the AGL platform code (meta-agl, meta-ivi-common, meta-oe, etc.). A subsystem may have a meta-data repository and/or multiple Code repositories
* In this context an App is any code that runs on the AGL platform and will generally be part of Code Repositories
* A role of App Maintainer can be envisioned, but since the App Developer has the power of +2 an App Maintainer was not included

Use Cases

App Developer Use Cases

- As an AD I want to write App code and approve code (+2) without getting +2 from anyone else.
- As an AD I want to write App code and request reviews from any other developers
- As an AD I want to submit patches to the AGL subsystems for review by SDs and SMs.

Subsystem Developer Use Cases

- On further review the SD role is identical to the RD and can be removed (Walt 21 Mar 2016)
- <del>As a SD I want to write code and submit it for review by other developers. They can be RDs, SDs and/or SMs<del>
- <del>As a SD I want to review code and approve or reject it. (+1, -1)</del>

Subsystem Maintainer Use Cases

- As a SM I want to review and approve code (+1,+2) submitted to my subsystem
- As a SM I want to review and reject code (-1,-2) submitted to my subsystem
- <del>As a SM I want to review and approve code (+1) submitted to my subsystem</del>
- As a SM I want to write code for my subsystem and submit for review by other developers (+1) and SMs (+1 or +2)
  - Alternate Scenario
    - As a SM I want to write code and push it to master without getting +2 from another SM
- As a SM I want to pull changes from upstream for the packages that are part of the subsystem.
- As a SM I want to push changes upstream for the packages that are part of the subsystem
- As a SM I want to back port new features (code) to AGL code from upstream. In some cases this will be patches and in some cases this is source code.
- As a SM I want to create branches to test changes prior to merging to the master branch.

Registered Developer Use Cases

- As a RD I want to download AGL pre-built binaries
- As a RD I want to write code for a subsystem and submit it for review (+1, +2) by SMs or RDs (+1)
- As a RD I want to write code for an existing app and submit it for review (+1, +2) by the ADs for the particular app.
- As a RD I want to review code and approve or reject it. (+1, -1)
- As a RD I want to be able to create a sandbox branch to develop code within the AGL build environment and share the sandbox branch with other RDs for collaboration
- As a RD I do not want other RDs to push to my sandbox branch
- As a RD I want to build other RDs sandbox branches in my environment and add changes using to it using my own sandbox branch.
- As a RD I want to push sandbox code into the AGL platform and have it maintained as part of the regular process. Once this is accomplished the AGL platform becomes the upstream for the formerly sandboxed code

Unregistered Developer Use Cases

System Integrator Use Cases

Release Manager

Documentation

Markdown format and Extensions

The documentation is written using Markdown format.

The developers site is generated using Jekyll which in turn uses Kramdown to generate HTML. Kramdown is compatible with most extensions introduced by PHP Markdown Extra

Here a the reference guides for Markdown syntax:

Markdown Editors

Here are some editors specialized in Markdown, in no particular order.

Online editors

Offline editors