2 title: General Guidelines
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.
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.
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.
30 ## Submitting your fix
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).
36 **NOTE:** If you need help with submitting your first CR, we have created a
37 brief [tutorial](04_Submitting_Changes.md) for you.
39 ## Fixing issues and working stories
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
49 ## Reviewing submitted Change Requests (CRs)
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.
62 Just browse through the [open CRs on
63 Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started.
65 ## Making Feature/Enhancement Proposals
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.
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
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
89 ## What makes a good change request?
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.
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.
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.
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.
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.
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
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](04_Submitting_Changes.md) for an acceptable change request.
137 **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item.
140 Bug-AGL: [SPEC-<JIRA-ID>] ....
142 Fix [SPEC-<JIRA-ID>] ....
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.
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.
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/).
159 Signed-off-by: John Doe <john.doe@example.com>
162 You can include this automatically when you commit a change to your local git
163 repository using ``git commit -s``.