1 |
Hi, |
2 |
|
3 |
As suggested earlier, here's a new doc&policy for review. Please do not |
4 |
edit the wiki page. I'm inlining the text in the mail to facilitate |
5 |
replying with quotations since our crappy wiki lacks any review system. |
6 |
|
7 |
https://wiki.gentoo.org/wiki/User:MGorny/Extra_proxy-maint_guide |
8 |
|
9 |
|
10 |
Content: |
11 |
|
12 |
==Privileges and responsibilities of proxied maintainers== |
13 |
What you get as a proxied maintainer: |
14 |
* ability to maintain ebuilds directly in the Gentoo repository for all |
15 |
our users to use; |
16 |
* coverage from our teams: QA, security; |
17 |
* coverage by package-oriented services: [http://euscan.gentooexperiment |
18 |
al.org euscan], [https://qa-reports.gentoo.org/ qa-reports], |
19 |
[https://repology.org/ repology]; |
20 |
* ability to request keywording on additional architectures (but note |
21 |
that most of arch teams are against proactive keywording) and to request |
22 |
stabilization; |
23 |
* quality reviews from our proxy-maint team and other Gentoo developers, |
24 |
* training and credibility needed to become a Gentoo developer. |
25 |
|
26 |
What you don't get: |
27 |
* ability to commit straight into the repository — all commits need to |
28 |
be reviewed and pushed by us, |
29 |
* full decision power — we restrict the right to reject or override your |
30 |
decisions at the review level, |
31 |
* ability to reject other maintainers — we encourage cooperation, not |
32 |
seclusion. |
33 |
|
34 |
Your responsibility is to maintain the package, that is: |
35 |
* address bugs reported against the package to the best of your skills, |
36 |
* bump the package to new versions in a reasonable time, |
37 |
* ensure that the package follows the best practices (preferably of our |
38 |
own accord), |
39 |
* clean old versions of the package up, request stabilization of new |
40 |
versions (if the package is stable), |
41 |
* inform us when you are no longer willing to maintain the package. |
42 |
|
43 |
The proxy-maint team is willing to help you with all those tasks. |
44 |
However, we expect that you at least keep the basic communication with |
45 |
us. |
46 |
|
47 |
==How to become a proxied maintainer== |
48 |
There is no special process for becoming a proxied maintainer — you |
49 |
become one when your first commit is merged. |
50 |
|
51 |
===Adding a new package=== |
52 |
As a proxied maintainer, you can add new packages to Gentoo, as long as |
53 |
you're willing to maintain them afterwards. In order to do so, please |
54 |
submit the initial package files using one of the submission methods. |
55 |
Make sure to include yourself and the proxy-maint project in the |
56 |
{{Path|metadata.xml}} files. |
57 |
|
58 |
Our team will review the submitted files and help you bring them to the |
59 |
top quality. Once the package is ready, we will merge it and close the |
60 |
relevant bugs (if there are any). |
61 |
|
62 |
Please note that we reserve the right to reject new packages, especially |
63 |
if they would otherwise qualify for removal per our quality standards: |
64 |
* they have known major bugs or security issues that you are unable to |
65 |
fix, |
66 |
* they have inactive upstream and maintaining them would require a lot |
67 |
of effort, |
68 |
* they require specific knowledge which we lack and which makes it |
69 |
inappropriate for us to review them (e.g. core system packages). |
70 |
|
71 |
===Taking over an existing package=== |
72 |
As a proxied maintainer, you can also (co-)maintain existing Gentoo |
73 |
packages (both those with no maintainer, maintained by other proxied |
74 |
maintainers and maintained by Gentoo developers/projects). In order to |
75 |
take over the maintenance of a package, submit a commit adding yourself |
76 |
to the {{Path|metadata.xml}} files. Usually, this commit will be |
77 |
included along with other changes to the package. |
78 |
|
79 |
There are a few points to consider: |
80 |
* If the package has an existing maintainer, he will be asked to ACK |
81 |
your changes and approve your request. Gentoo developers can reject a |
82 |
proxied maintainer if they have a good reason to do so. |
83 |
* If the package has major bugs qualifying it for removal (esp. if |
84 |
you're taking over maintenance in reply to last rites), you will be |
85 |
required to provide a fix at least for the most nagging issues. |
86 |
* If you do not have major prior contributions as a proxied maintainer, |
87 |
you will be required to do some additional changes to the package — for |
88 |
example, fix some bug(s) and/or update the package to the modern coding |
89 |
standards. |
90 |
|
91 |
==How to submit package updates== |
92 |
===GitHub pull requests=== |
93 |
The preferred way of submitting your contributions is through [https://g |
94 |
ithub.com/gentoo/gentoo/pulls pull requests on our GitHub repository]. |
95 |
At the moment, it gives the best response time, and the widest audience |
96 |
for reviews. |
97 |
|
98 |
In order to submit a pull request, fork the repository, create a new |
99 |
branch and commit your changes there. Afterwards, [https://help.github.c |
100 |
om/articles/creating-a-pull-request/ create a pull request]. |
101 |
|
102 |
{{Tip|Once you push your new branch, visit the GitHub page of your fork. |
103 |
GitHub will show you a banner suggesting creating a pull request. Using |
104 |
it, you can avoid the necessity of specifying the fork and branch |
105 |
manually.}} |
106 |
|
107 |
Once the pull request is created, our tooling will automatically CC the |
108 |
relevant people (maintainers and/or proxy-maint team) and perform basic |
109 |
QA checks via [https://github.com/pkgcore/pkgcheck pkgcheck]. If any |
110 |
issues are reported, please fix them or explicitly ask for help. Our |
111 |
reviewers may skip pull requests which are marked as not passing CI. |
112 |
|
113 |
Afterwards, follow the suggestions given by reviewers and push updates |
114 |
until the pull request is fully approved. If you do not receive a reply |
115 |
within a reasonable time, please make sure to ping us on the pull |
116 |
request. When it's ready and approved, we'll merge it. |
117 |
|
118 |
It is recommended that you try to keep the same commit structure as |
119 |
you'd use when committing straight to Gentoo as a developer, and follow |
120 |
the best git practices (atomic changes, proper commit messages). For |
121 |
smaller changes, we can squash and reword the commits for you. However, |
122 |
if you're going to actively maintain multiple packages or submit larger |
123 |
changes, we will require you to squash, split and word your commits |
124 |
appropriately. Please see the git documentation on [https://git-scm.com/ |
125 |
book/en/v2/Git-Tools-Rewriting-History rewriting history]. Once you've |
126 |
got updated commit set, use <code>git push --force</code> to overwrite |
127 |
your previous commits on the pull request branch. |
128 |
|
129 |
===Mailing list patches=== |
130 |
{{Note|This variant has not been tested by anyone yet.}} |
131 |
|
132 |
The alternative to GitHub is to use the [https://archives.gentoo.org/gen |
133 |
too-proxy-maint/ gentoo-proxy-maint@l.g.o] mailing list. In |
134 |
order to use the list, you need to [mailto:gentoo-proxy- |
135 |
maint+subscribe@l.g.o subscribe] first. Once you've confirmed |
136 |
your subscription, you should be able to send patches for review. |
137 |
|
138 |
Please prepare your commits just like you would for a pull request. |
139 |
Afterwards, use <kbd>git send-email</kbd> to send them to the mailing |
140 |
list. For help on it, please see [https://www.freedesktop.org/wiki/Softw |
141 |
are/PulseAudio/HowToUseGitSendEmail/ how to use git send-email] (a good |
142 |
guide from pulseaudio wiki — please remember to correct the mailing list |
143 |
address). |
144 |
|
145 |
Once your initial patch set is submitted, the proxy-maint team members |
146 |
will reply with their review comments. Once you address a particular set |
147 |
of issues, please update the commits and send another batch of patches |
148 |
'''in reply to the original message''' (using the <kbd>--in-reply- |
149 |
to</kbd> option), using the next version number. It is important that |
150 |
you follow this practice so that everyone can find the newest version of |
151 |
the commits easily. |
152 |
|
153 |
Similar practices as with GitHub pull requests apply — try to keep the |
154 |
commit structure clean and suitable for direct merge. Similarly to pull |
155 |
requests, this method can preserve commit structure and attribution but |
156 |
it does not support automatic assignment or CI. |
157 |
|
158 |
===Bug reports=== |
159 |
The classical method of submitting your changes is to attach them to the |
160 |
bugs. Please make sure that the proxy-maint project is in CC of the bugs |
161 |
related to proxy-maintained packages. |
162 |
|
163 |
Preferably, structure your changes as git commits and attach patches |
164 |
created using <kbd>git format-patch</kbd>. Attaching single files is |
165 |
inconvenient for the developers who have to review and download every |
166 |
file separately. Attaching tarballs is strongly discouraged as it makes |
167 |
review with quotation impossible. |
168 |
|
169 |
When you have attached changes that are ready for review, please make |
170 |
sure to mark the bug with both ''EBUILD'' and ''PATCH'' keywords. |
171 |
|
172 |
|
173 |
==Being a proxied maintainer== |
174 |
===CI vs repoman=== |
175 |
If you are using the pull request workflow, your submissions are |
176 |
verified by the CI system. Nevertheless, you are still expected to use |
177 |
repoman to commit or verify your ebuilds before/after committing. |
178 |
|
179 |
Note that both CI and repoman do not test experimental (and developer) |
180 |
profiles by default. The skipped profiles include: |
181 |
* all profiles for arm64, m68k, mips, nios2, riscv, s390, sh, |
182 |
* all profiles for FreeBSD and Prefix, |
183 |
* some less common profiles, e.g. no-multilib amd64 or x32 profiles. |
184 |
|
185 |
You need to explicitly use <kbd>repoman full -e y</kbd> to verify the |
186 |
experimental profiles. |
187 |
|
188 |
===Proxied maintainer in metadata.xml=== |
189 |
Proxied maintainers are listed in {{Path|metadata.xml}} like any other |
190 |
maintainers. The only difference is that since they can not commit on |
191 |
their own, the proxy-maint project is listed as well to facilitate |
192 |
committing. The proxy-maint project is always listed ''after'' proxied |
193 |
maintainers since it does not maintain the package on its own. |
194 |
|
195 |
{{FileBox|title=Example metadata.xml for a package that is co-maintained |
196 |
by a proxied maintainer (primary) and Perl project (co- |
197 |
maintainer)|filename=metadata.xml|lang=xml|1=<?xml version="1.0" |
198 |
encoding="UTF-8"?> |
199 |
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">; |
200 |
|
201 |
<pkgmetadata> |
202 |
<maintainer type="person"> |
203 |
<email>author@×××××××.com</email> |
204 |
<name>A. U. Thor</name> |
205 |
</maintainer> |
206 |
<maintainer type="project"> |
207 |
<email>perl@g.o</email> |
208 |
<name>>Gentoo Perl Project</name> |
209 |
</maintainer> |
210 |
<maintainer type="project"> |
211 |
<email>proxy-maint@g.o</email> |
212 |
<name>Proxy Maintainers</name> |
213 |
</maintainer> |
214 |
</pkgmetadata>}} |
215 |
|
216 |
===Resolving bugs=== |
217 |
As a proxied maintainer, you are expected to handle bugs against your |
218 |
packages yourself. This includes resolving them once your fix is merged |
219 |
by a proxy maintainer or rejecting them based on your own judgment. |
220 |
|
221 |
The Bugzilla permissions for regular users allow them to resolve only |
222 |
bugs that they are either assignee or reporter of. At the same time, it |
223 |
permits only one assignee meaning that the remaining assignees are added |
224 |
to the CC field. If that is the case for you, you will have to ask us to |
225 |
close the bug for you. |
226 |
|
227 |
Once you have a few good contributions, we can vouch for providing the |
228 |
''editbugs'' group membership to you. It will allow you to edit all |
229 |
Gentoo bugs, including resolving and reassigning them. |
230 |
|
231 |
===Keywording & stabilization=== |
232 |
As a proxied maintainer, you can request [https://devmanual.gentoo.org/k |
233 |
eywording/index.html keywording and stabilization] of your packages. |
234 |
However, all those requests need to be approved by proxy-maint team |
235 |
member (or a regular developer co-maintainer) first. |
236 |
|
237 |
===Cleaning up old ebuilds=== |
238 |
To avoid cluttering the repository with old ebuilds, it is recommended |
239 |
that you clean them up either periodically or on version bumps (if you |
240 |
do not expect to stabilize the specific old version). Please remember to |
241 |
remove old patches and other misc files along with the old versions, and |
242 |
to verify that the package has no reverse dependencies that depend on |
243 |
the old version. |
244 |
|
245 |
If you are using the GitHub pull request workflow, then the CI will |
246 |
verify that your commits do not break reverse dependencies on major |
247 |
profiles. However, note that experimental and developer profiles are not |
248 |
tested currently. |
249 |
|
250 |
===The maintainer bug=== |
251 |
Since proxied maintainers do not have full access to the Gentoo |
252 |
developer services, the proxy-maint project is using ''maintainer bugs'' |
253 |
to track status of the proxied maintainers. |
254 |
|
255 |
Once your first contribution is merged, we will create the maintainer |
256 |
bug for you. We will note your name and/or nickname (for communication |
257 |
purposes) and your e-mail address used in metadata.xml. We will |
258 |
afterwards use the bug to track the changes in your e-mail address and |
259 |
your contributor status. |
260 |
|
261 |
If you ever change your Bugzilla e-mail address, please remember to |
262 |
submit an update to your package {{Path|metadata.xml}} files. We will |
263 |
also note the new e-mail address on the maintainer bug. |
264 |
|
265 |
If you go on vacation or otherwise expect to be unavailable for a period |
266 |
of time, please note that on the maintainer bug. You can use the |
267 |
''whiteboard'' field to provide the expected return date and any |
268 |
requests wrt handling the bugs on your packages (i.e. whether other |
269 |
developers should merge fixes in your absence). |
270 |
|
271 |
==How to step down as a proxied maintainer== |
272 |
If you decide that you don't want to maintain some of your packages |
273 |
anymore, please follow the following procedure: |
274 |
# If you are the last maintainer of some of the packages (not counting |
275 |
proxy-maint project), please send an email to [[mailto:gentoo-dev@lists. |
276 |
gentoo.org gentoo-dev@l.g.o] mailing list titled 'Packages up |
277 |
for grabs: …' and listing all packages that you are no longer willing to |
278 |
maintain. It is usually a good idea to shortly describe the state of |
279 |
packages, i.e. whether the packages have open bugs, whether they are |
280 |
hard to maintain etc. |
281 |
# Submit a patch removing yourself from the {{Path|metadata.xml}} files |
282 |
of the packages: |
283 |
#* If you are the last proxied maintainer of the package, remove the |
284 |
proxy-maint project along with you. |
285 |
#* If you are the last maintainer of the package, please insert a |
286 |
comment stating exactly: |
287 |
#*:<pre><nowiki><!--maintainer-needed--></nowiki></pre> |
288 |
#*:in the place of maintainers. This will help other developers to grep |
289 |
packages with no maintainers. |
290 |
|
291 |
-- |
292 |
Best regards, |
293 |
Michał Górny |