docs/5_How_To_Contribute/7_General_Guidelines.md

   1 ---
   2 title: General Guidelines
   3 ---
   4
   5 ## Getting help
   6
   7 If you are looking for something to work on, or need some expert
   8 assistance in debugging a problem or working out a fix to an issue, our
   9 community is always eager to help. We hang out on various
  10 [developer meetings](https://www.automotivelinux.org/developer-meetings/),
  11 IRC (#automotive on freenode.net) and the
  12 [mailing lists](https://lists.automotivelinux.org/g/agl-dev-community).
  13 We will be glad to help. The only silly question is the one you don't ask.
  14 Questions are in fact a great way to help improve the project as they highlight
  15 where our documentation could be clearer.
  16
  17 ## Reporting bugs
  18
  19 If you are a user and you have found a bug, please submit an issue using
  20 [JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA
  21 issue, please try to search the existing items to be sure no one else has
  22 previously reported it. If it has been previously reported, then you
  23 might add a comment that you also are interested in seeing the defect
  24 fixed.
  25
  26 If it has not been previously reported, create a new JIRA. Please try to
  27 provide sufficient information for someone else to reproduce the issue.
  28 One of the project's maintainers should respond to your issue within 24
  29 hours. If not, please bump the issue with a comment and request that it
  30 be reviewed.
  31
  32 ## Submitting your fix
  33
  34 If you just submitted a JIRA for a bug you've discovered, and would like to
  35 provide a fix, we would welcome that gladly! Please assign the JIRA issue to
  36 yourself, then you can submit a change request (CR).
  37
  38 **NOTE:** If you need help with submitting your first CR, we have created
  39 a brief [tutorial](./4_Submitting_Changes.md) for you.
  40
  41 ## Fixing issues and working stories
  42
  43 Review the [open issue list](https://jira.automotivelinux.org/issues/?filter=-5) and find
  44 something that interests you. It is wise to start with something
  45 relatively straight forward and achievable, and that no one is already
  46 assigned. If no one is assigned, then assign the issue to yourself.
  47 Please be considerate and rescind the assignment if you cannot finish in
  48 a reasonable time, or add a comment saying that you are still actively
  49 working the issue if you need a little more time.
  50
  51 ## Reviewing submitted Change Requests (CRs)
  52
  53 Another way to contribute and learn about Automotive Grade Linux is to help the
  54 maintainers with the review of the CRs that are open. Indeed
  55 maintainers have the difficult role of having to review all the CRs
  56 that are being submitted and evaluate whether they should be merged or
  57 not. You can review the code and/or documentation changes, test the
  58 changes, and tell the submitters and maintainers what you think. Once
  59 your review and/or test is complete just reply to the CR with your
  60 findings, by adding comments and/or voting. A comment saying something
  61 like "I tried it on system X and it works" or possibly "I got an error
  62 on system X: xxx " will help the maintainers in their evaluation. As a
  63 result, maintainers will be able to process CRs faster and everybody
  64 will gain from it.
  65
  66 Just browse through the [open CRs on Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started.
  67
  68 ## Making Feature/Enhancement Proposals
  69
  70 Review [JIRA](https://jira.automotivelinux.org/) to be sure that there
  71 isn't already an open (or recently closed) proposal for the same
  72 function. If there isn't, to make a proposal we recommend that you open a
  73 JIRA Epic, Story or Improvement, whichever seems to best fit the
  74 circumstance and link or inline a "one pager" of the proposal that states
  75 what the feature would do and, if possible, how it might be implemented.
  76 It would help also to make a case for why the feature should be added,
  77 such as identifying specific use case(s) for which the feature is needed
  78 and a case for what the benefit would be should the feature be
  79 implemented. Once the JIRA issue is created, and the "one pager" either
  80 attached, inlined in the description field, or a link to a publicly
  81 accessible document is added to the description, send an introductory
  82 email to the [agl-dev community](mailto:agl-dev-community@lists.automotivelinux.org) mailing
  83 list linking the JIRA issue, and soliciting feedback.
  84
  85 Discussion of the proposed feature should be conducted in the JIRA issue
  86 itself, so that we have a consistent pattern within our community as to
  87 where to find design discussion.
  88
  89 Getting the support of three or more of the AGL maintainers for the new
  90 feature will greatly enhance the probability that the feature's related
  91 CRs will be merged.
  92
  93 ## What makes a good change request?
  94
  95 -  One change at a time. Not five, not three, not ten. One and only one.
  96    Why? Because it limits the blast area of the change. If we have a
  97    regression, it is much easier to identify the culprit commit than if
  98    we have some composite change that impacts more of the code.
  99
 100 -  Include a link to the JIRA story for the change. Why? Because a) we
 101    want to track our velocity to better judge what we think we can
 102    deliver and when and b) because we can justify the change more
 103    effectively. In many cases, there should be some discussion around a
 104    proposed change and we want to link back to that from the change
 105    itself.
 106
 107 -  Include unit and integration tests (or changes to existing tests)
 108    with every change. This does not mean just happy path testing,
 109    either. It also means negative testing of any defensive code that it
 110    correctly catches input errors. When you write code, you are
 111    responsible to test it and provide the tests that demonstrate that
 112    your change does what it claims. Why? Because without this we have no
 113    clue whether our current code base actually works.
 114
 115 -  Minimize the lines of code per CR. Why? If you send a 1,000 or 2,000
 116 LOC change, how long do you think it takes to review all of that code?
 117 Keep your changes to < 200-300 LOC, if possible. If you have a larger
 118 change, decompose it into multiple independent changess. If you are
 119 adding a bunch of new functions to fulfill the requirements of a new
 120 capability, add them separately with their tests, and then write the code
 121 that uses them to deliver the capability. Of course, there are always
 122 exceptions. If you add a small change and then add 300 LOC of tests, you
 123 will be forgiven;-) If you need to make a change that has broad impact or
 124 a bunch of generated code (protobufs, etc.). Again, there can be
 125 exceptions.
 126
 127       **NOTE:** Large change requests, e.g. those with more than 300 LOC
 128       are more likely than not going to receive a -2, and you'll be asked
 129       to refactor the change to conform with this guidance.
 130
 131 -  Do not stack change requests (e.g. submit a CR from the same local branch
 132    as your previous CR) unless they are related. This will minimize merge
 133    conflicts and allow changes to be merged more quickly. If you stack requests
 134    your subsequent requests may be held up because of review comments in the
 135    preceding requests.
 136
 137 -  Write a meaningful commit message. Include a meaningful 50 (or less)
 138    character title, followed by a blank line, followed by a more
 139    comprehensive description of the change. Each change MUST include the JIRA
 140    identifier corresponding to the change (e.g. [SPEC-1234]). This can be
 141    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
 142    request.
 143
 144    **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item.
 145
 146    ```sh
 147    Bug-AGL: [SPEC-<JIRA-ID>] ....
 148
 149    Fix [SPEC-<JIRA-ID>] ....
 150    ```
 151
 152 Finally, be responsive. Don't let a change request fester with review
 153 comments such that it gets to a point that it requires a rebase. It only
 154 further delays getting it merged and adds more work for you - to
 155 remediate the merge conflicts.
 156
 157 ## Legal stuff
 158
 159 We have tried to make it as easy as possible to make contributions. This
 160 applies to how we handle the legal aspects of contribution.
 161
 162 We simply ask that when submitting a patch for review, the developer must
 163 include a sign-off statement in the commit message.
 164
 165 ```sh
 166 Signed-off-by: John Doe <john.doe@example.com>
 167 ```
 168
 169 You can include this automatically when you commit a change to your
 170 local git repository using ``git commit -s``.