1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
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-<JIRA-ID>] ....
Fix [SPEC-<JIRA-ID>] ....
```
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 <john.doe@example.com>
```
You can include this automatically when you commit a change to your
local git repository using ``git commit -s``.
|
