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