ebuild-writing/user-submitted/text.xml


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

<?xml version="1.0" encoding="UTF-8"?>
<devbook self="ebuild-writing/user-submitted/">
<chapter>
<title>User-submitted ebuilds</title>

<body>

<p>
User-submitted ebuilds should never be blindly trusted and should
always be well-tested and audited before being committed to the tree.
The developer committing the user-submitted ebuild is vouching that
the ebuild meets all Gentoo Linux development standards.
</p>

<p>
The user-submitted ebuild must not contain custom headers like this:
</p>

<pre>
# Ebuild updated by: me &lt;me@example.com&gt;
</pre>

<p>
Such information should be included in the git commit message instead.
The use of tags such as <c>Suggested-By:</c> or <c>Reported-By:</c> in
the commit message, as explained in the
<uri link="::ebuild-maintenance/git/#Git commit message format">
commit message format section</uri>, is highly encouraged.
Note that ebuilds received in the form of git patches or pull requests
will have the user as the commit author by default, in which case
including the user information in the commit message explicitly
may not be necessary. If that is not the case, you may wish to use
git commit's <c>--author</c> parameter to explicitly give them credit.
</p>

<p>
Developers must check for a valid <c>Signed-off-by</c> line either within
the provided patches by a user or within a comment on e.g. Bugzilla.
See <uri link="::general-concepts/copyright-policy/#Certificate of Origin"/>
for details.
</p>

<p>
Users should be encouraged to submit diffs to an existing ebuild if they
are submitting an upgrade. Doing this will help to avoid re-introduction
of previously fixed bugs into "new" ebuilds. When not working from a
diff but from a complete user-submitted ebuild, the <c>diff -u</c> command
should be used to see what has changed; attention should be payed for
anything from the current ebuild that should appear in the new ebuild,
or anything in the new ebuild that should be fixed or removed.
</p>

<p>
In general, it is preferable to have the user do the work required to
get their ebuild up to par, so that they can learn from their mistakes
and submit cleaner ebuilds in the future. Be sure to be thankful for any
submission, even if it isn't very good. Be polite but honest <d/> if an
ebuild isn't usable, the user can be told in a way that does not insult
their current ebuild-writing abilities. Remember that the user who
submitted that broken ebuild may be a skilled and productive member of
our project in the future <d/> that is, if they receive the right amount
of encouragement and support and continue to improve in their abilities.
</p>

</body>
</chapter>
</devbook>