X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2F5_How_To_Contribute%2F7_General_Guidelines.md;fp=docs%2F5_How_To_Contribute%2F7_General_Guidelines.md;h=cc0ece5fc203e6dbba06d1a364c95d343a49b48b;hb=de81a8b07f8139fa0f65dddffc839b4a5e83dad7;hp=0000000000000000000000000000000000000000;hpb=13dda7db03587f9aa6d8095207e0d126b32141c7;p=AGL%2Fdocumentation.git diff --git a/docs/5_How_To_Contribute/7_General_Guidelines.md b/docs/5_How_To_Contribute/7_General_Guidelines.md new file mode 100644 index 0000000..cc0ece5 --- /dev/null +++ b/docs/5_How_To_Contribute/7_General_Guidelines.md @@ -0,0 +1,170 @@ +--- +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. + +```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``.