-
-
Notifications
You must be signed in to change notification settings - Fork 56
/
Copy pathCONTRIBUTING
181 lines (138 loc) · 9.61 KB
/
CONTRIBUTING
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
171
172
173
174
175
176
177
178
179
180
181
Contributing to Dinit's development
===================================
This is a guide to contributing to Dinit. It should be read from start to finish before attempting
to make a contribution to the Dinit codebase or documentation.
Note: Yes, this is a lot of text (especially since it refers to information contained in other
files). Having a proper process for contribution is important for maintainer sanity and to
avoid burn-out.
Before making a contribution
----------------------------
Many open-source project have limited resources, in particular people-power. While this might seem
to make any outside contribution desirable, that's not always the case. Before making a
contribution, you should consider:
- whether or not the contribution is generally useful (is it just scratching a personal itch?).
- whether the contribution being accepted will create a maintenance/development burden going
forward, and whether you are prepared to assist with that burden (or whether the benefit
outweighs the cost generally).
- whether the change fits in with the philosophy and design direction of the project. For
contribution of new features, the only way for sure is often to ask the maintainers - preferably
before you've done the work, since it isn't so nice to put work into someone else's project only
to be told it's not wanted!
- whether the change will be convenient for users and other developers. Introducing build-time
dependencies, for example, may cause inconvenience. Does the benefit of the change really
outweigh this?
Documentation contributions are often appreciated, though you should be careful to ensure that the
style and conventions used match those of the existing documentation.
Bugfixes, likewise, are usually appreciated. However, it's important to understand whether what you
are fixing really is a bug, or whether it's intended behaviour - if there's any doubt at all, you
should ask the maintainers. Also, if the proposed fix is not completely straight-forward or is
"hacky", you should consider discussing it with maintainers first.
Remember:
- submitting a merge request is an act that, by itself, creates work for the maintainer(s)!
- always talk to the maintainers before doing a significant amount of work on a project, and
consider doing so before commencing even minor work.
- if you disagree with a maintainer, you need to consider who has invested more in the project.
Maintainers will often have a good "feel" for how their software should work, and they may have
a philosophy that doesn't align with your own. Arguing over subjective issues may frustrate both
parties. It may be better to let it go!
Importantly: you should not rely on the maintainers to ensure your changes/additions are suitable
and correct. That is your job! If you are not capable (do not have the necessary technical
expertise, or are not willing or able to spend the time to properly adhere to contribution
requirements), then please do not try to contribute. Maintainers do not have the resources to
instruct you or guide you through the process. (You are welcome to request mentoring, before
attempting to make a contribution, in a discussion; please accept however that you may not get a
response).
Dinit is critical system software. If you are not aware of how that affects the way that it should
be designed and coded, then you probably do not have the expertise required to contribute.
I will endeavour to respond to all offered contributions with civility and respect, even if I
choose not to accept them.
Code contributions
------------------
In general, code contributions:
- should follow existing style and conventions (also: read and follow CODE-STYLE)
- should be appropriately* commented in accordance with existing style
- should keep the design considerations in mind (read the DESIGN document)
- should be accompanied by appropriate documentation additions/updates
- should include tests where practical
[*] There is a little lee-way for comments, "truly obvious" code does not need to be and should
not be commented.
As the maintainer and original author, I maintain the right to reject or request modification to
contributions, for failure to comply with the points listed above, for failure to adhere to a
reasonable standard of conduct (see Contributor Conduct below), or because I deem that the
contribution includes features outside the intended scope. I encourage anyone who is considering
making a contribution to contact me to sound out whether I would be likely to accept a submission
for a particular feature or behavioural change.
Documentation contributions
---------------------------
Many code contributions require accompanying documentation contributions, and it is possible to
contribute appropriate documentation by itself if applicable.
Documentation (including comments in code) should be:
- Consistent: in terminology, style and tone, with existing documentation and itself.
- Clear, unambiguous, and correct.
- Written for the audience. Do not use developer-centric terminology/language in end-user
documentation.
- Grammatically correct, and correctly spelled. Use a checker if you are not comfortable enough
with English. Do not invent terms. Do not use unnecessary abbreviations unless they are very
commonly used elsewhere. (We have some tolerance for mistakes, but the onus is still on you
to make a best effort).
- No shorter, but also no longer, than it needs to be. If discussing other software, keep the
discussion restricted to what is necessary for understanding Dinit's interaction or own
behaviour.
- Link/refer to other information (man pages, documentation) where appropriate. However, be aware
of web impermanence: if linking to a web resource that may not be permanent, try (if practical)
to replicate the necessary information in documentation, and/or explain what was linked to (so
that a reader can perhaps find it even if it has moved).
For comments in code, some additional concerns apply:
- To document classes, functions and variables, see notes in CODE-STYLE.
- Use comments to explain anything in the code that is not apparent or any aspect that has
significance beyond what is apparently just be reading the code. Be specific.
- Do not simply state what the code does in code terms.
Examples of good/bad code comments:
"Call foo() now" - bad, just saying what is obvious from reading the code.
"We need to account for the string terminator" - ok (explanatory), but could be better.
"Some OSes require us to call frob() after sniggle()" - could be better (which OSes, why?).
"We +1 here to account for the string terminator" - good, explanatory.
"Not that since ziggle was set to true above, this call to frobnicate() is guaranteed to return
without an error" - good, adds explanatory context.
Using code/documentation from elsewhere
---------------------------------------
In general you should not use code (including comments) or documentation from any other project or
external source. This is true even for small snippets, and even if you make modifications. It is
preferable to write new code and documentation from scratch. The only exception is if the code is
identically licensed or is available under permissive terms that allow it to be distributed under
the same license as Dinit.
If you do use anything from another project in a contribution, you must make the reviewer
(maintainer) aware of what you have used, where it is from, and why you believe it is reasonable
to use it, and why you believe that it does not infringe copyright.
Contributor Conduct
-------------------
There is no complete "code of conduct" for Dinit contributors, but contributions will only be
accepted from those who are civil and respectful towards others. Specific behaviours that won't
be tolerated from contributors include but are not limited to:
- discrimination generally, and especially if based on race, gender or gender identity, sexual
preference, etc
- personal attacks, insults, or harassment, or incitement thereof, against others
- unnecessarily drawing attention to another's private or personal details
If a person is deemed to have engaged in negative behaviour such as from the list above,
contributions from them will not be accepted and the perpetrator may be blocked from
communications related to Dinit development. Note that such negative behaviours need not have
occurred in a public forum, and need not be related to Dinit development.
In short: don't be nasty to others; arseholes won't be tolerated.
If you feel that a contributor has behaved inappropriately, please feel free to contact me to
discuss it; such communication will be kept confidential (unless and until otherwise agreed).
New contributors
----------------
New contributors should introduce themselves briefly when making a contribution. If this applies
to you, please briefly explain your interest in Dinit, and outline your relevant experience
to software development (eg list one or two other projects you have worked on).
Finally, new contributors must acknowledge that they have read and understood this document, by
including this exact text in the introduction to the pull request (or patch email):
I have read and understand the CONTRIBUTING guide in full.
Failure to include this will result in the PR being marked as a draft (or equivalent) with an
explanatory note.
Contributors should feel free to add themselves to the CONTRIBUTORS list as part of the patch/pull
request.
Process for contributing
------------------------
The preferred way to contribute is via a pull request (PR). See PR-PROCESS for details of the
expectations on contributors and how the process operates.