1 |
commit: d1305e90f89c11aa226c0c88224b12744a711a6f |
2 |
Author: Michał Górny <mgorny <AT> gentoo <DOT> org> |
3 |
AuthorDate: Mon Oct 9 22:04:00 2017 +0000 |
4 |
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> |
5 |
CommitDate: Sat Oct 14 09:16:38 2017 +0000 |
6 |
URL: https://gitweb.gentoo.org/data/glep.git/commit/?id=d1305e90 |
7 |
|
8 |
Import GLEP 66 from wiki |
9 |
|
10 |
https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git |
11 |
|
12 |
glep-0066.rst | 458 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
13 |
1 file changed, 458 insertions(+) |
14 |
|
15 |
diff --git a/glep-0066.rst b/glep-0066.rst |
16 |
new file mode 100644 |
17 |
index 0000000..8eabec0 |
18 |
--- /dev/null |
19 |
+++ b/glep-0066.rst |
20 |
@@ -0,0 +1,458 @@ |
21 |
+--- |
22 |
+GLEP: 66 |
23 |
+Title: Gentoo Git Workflow |
24 |
+Author: Michał Górny <mgorny@g.o> |
25 |
+Type: Standards Track |
26 |
+Status: Draft |
27 |
+Version: 1 |
28 |
+Created: 2017-07-24 |
29 |
+Last-Modified: 2017-10-09 |
30 |
+Post-History: 2017-07-25, 2017-09-28 |
31 |
+Content-Type: text/x-rst |
32 |
+Requires: |
33 |
+Replaces: |
34 |
+--- |
35 |
+ |
36 |
+Abstract |
37 |
+======== |
38 |
+This GLEP specifies basic standards and recommendations for using git |
39 |
+with the Gentoo ebuild repository. It covers only Gentoo-specific |
40 |
+policies, and is not meant to be a complete guide. |
41 |
+ |
42 |
+ |
43 |
+Motivation |
44 |
+========== |
45 |
+Although the main Gentoo repository is using git for two years already, |
46 |
+developers still lack official documentation on how to use git |
47 |
+consistently. Most of the developers learn spoken standards from others |
48 |
+and follow them. This eventually brings consistency to some extent |
49 |
+but is suboptimal. Furthermore, it results in users having to learn |
50 |
+things the hard way instead of having proper documentation to follow. |
51 |
+ |
52 |
+There were a few attempts to standardize git use over the time. Most |
53 |
+noteworthy are Gentoo git workflow [#GENTOO_GIT_WORKFLOW]_ |
54 |
+and Gentoo GitHub [#GENTOO_GITHUB]_ articles. However, they are not any |
55 |
+kind of official standards, and they have too broad focus to become one. |
56 |
+There was also an initial GLEP attempt but it never even reached |
57 |
+the draft stage. |
58 |
+ |
59 |
+This GLEP aims to finally provide basic standardization for the use of |
60 |
+git in the Gentoo repository. It aims to focus purely |
61 |
+on Gentoo-specific standards and not git usage in general. It doesn't |
62 |
+mean to be a complete guide but a formal basis on top of which official |
63 |
+guides could be created. |
64 |
+ |
65 |
+ |
66 |
+Specification |
67 |
+============= |
68 |
+ |
69 |
+Branching model |
70 |
+--------------- |
71 |
+The main branch of the Gentoo repository is the ``master`` branch. All |
72 |
+Gentoo developers push their work straight to the master branch, |
73 |
+provided that the commits meet the minimal quality standards. |
74 |
+The master branch is also used straight for continuous user repository |
75 |
+deployment. |
76 |
+ |
77 |
+Since multiple developers work on master concurrently, they may be |
78 |
+required to rebase multiple times before being able to push. Developers |
79 |
+are requested not to use workflows that could prevent others from |
80 |
+pushing, e.g. pushing single commits frequently instead of staging them |
81 |
+and using a single push. |
82 |
+ |
83 |
+Developers can use additional branches to facilitate review and testing |
84 |
+of long-term projects of larger scale. However, since git fetches all |
85 |
+branches by default, they should be used scarcely. For smaller |
86 |
+projects, local branches or repository forks are preferred. |
87 |
+ |
88 |
+Unless stated otherwise, the rules set by this specification apply to |
89 |
+the master branch only. The development branches can use relaxed rules. |
90 |
+ |
91 |
+Rewriting history (i.e. force pushes) of the master branch is forbidden. |
92 |
+ |
93 |
+ |
94 |
+Merge commits |
95 |
+------------- |
96 |
+The use of merge commits in the Gentoo repository is strongly |
97 |
+discouraged. Usually it is preferable to rebase instead. However, |
98 |
+the developers are allowed to use merge commits in justified cases. |
99 |
+Merge commits can be only used to merge additional branches, the use |
100 |
+of implicit ``git pull`` merges is entirely forbidden. |
101 |
+ |
102 |
+In a merge commit that is committed straight to the Gentoo repository, |
103 |
+the first parent is expected to reference an actual Gentoo commit |
104 |
+preceding the merge, while the remaining parents can be used to |
105 |
+reference external repositories. The commits following the first parent |
106 |
+are required to conform to this specification alike regular Gentoo |
107 |
+commits. The additional commits following other parents can use relaxed |
108 |
+rules. |
109 |
+ |
110 |
+ |
111 |
+OpenPGP signatures |
112 |
+------------------ |
113 |
+Each commit in the Gentoo repository must be signed using |
114 |
+the committer's OpenPGP key. Furthermore, each push to the repository |
115 |
+must be signed using the key belonging to the developer performing |
116 |
+the push (matched via the SSH key). |
117 |
+ |
118 |
+The requirements for OpenPGP keys are covered by GLEP 63 [#GLEP63]_. |
119 |
+ |
120 |
+ |
121 |
+Splitting commits |
122 |
+----------------- |
123 |
+Git commits are lightweight, and the developers are encouraged to split |
124 |
+their commits to improve readability and the ability of reverting |
125 |
+specific sub-changes. When choosing how to split the commits, |
126 |
+the developers should consider the following three rules: |
127 |
+ |
128 |
+1. Use atomic commits — one commit per logical change. |
129 |
+2. Split commits at logical unit (package, eclass, profile…) boundaries. |
130 |
+3. Avoid creating commits that are 'broken' — e.g. are incomplete, have |
131 |
+ uninstallable packages. |
132 |
+ |
133 |
+It is technically impossible to always respect all of the three rules, |
134 |
+so developers have to balance between them at their own discretion. |
135 |
+Side changes that are implied by other change (e.g. revbump due to some |
136 |
+change) should be included in the first commit requiring them. Commits |
137 |
+should be ordered to avoid breakage, and follow logical ordering |
138 |
+whenever possible. |
139 |
+ |
140 |
+Examples: |
141 |
+ |
142 |
+- When doing a version bump, it is usually not reasonable to split every |
143 |
+ necessary logical change into separate commit since the interim |
144 |
+ commits would correspond to a broken package. However, if the package |
145 |
+ has a live ebuild, it *might* be reasonable to perform split logical |
146 |
+ changes on the live ebuild, then create a release as another logical |
147 |
+ step. |
148 |
+ |
149 |
+- When doing one or more changes that require a revision bump, bump |
150 |
+ the revision in the commit including the first change. Split |
151 |
+ the changes into multiple logical commits without further revision |
152 |
+ bumps — since they are going to be pushed in a single push, the user |
153 |
+ will not be exposed to interim state. |
154 |
+ |
155 |
+- When adding a new version of a package that should be masked, you can |
156 |
+ include the ``package.mask`` edit in the commit adding it. |
157 |
+ Alternatively, you can add the mask in a split commit *preceding* |
158 |
+ the bump. |
159 |
+ |
160 |
+- When doing a minor change to a large number of packages, it is |
161 |
+ reasonable to do so in a single commit. However, when doing a major |
162 |
+ change (e.g. a version bump), it is better to split commits on package |
163 |
+ boundaries. |
164 |
+ |
165 |
+ |
166 |
+Commit messages |
167 |
+--------------- |
168 |
+A standard git commit message consists of three parts, in order: |
169 |
+a summary line, an optional body and an optional set of tags. The parts |
170 |
+are separated by a single empty line. |
171 |
+ |
172 |
+The summary line is included in the short logs (``git log --oneline``, |
173 |
+gitweb, GitHub, mail subject) and therefore should provide a short yet |
174 |
+accurate description of the change. The summary line starts with |
175 |
+a logical unit name, followed by a colon, a space and a short |
176 |
+description of the most important changes. If a bug is associated with |
177 |
+a change, then it can be included in the summary line |
178 |
+as ``bug #nnnnnn``. The summary line must not exceed 69 characters, |
179 |
+and must not be wrapped. |
180 |
+ |
181 |
+The suggested logical unit name formats are: |
182 |
+ |
183 |
+- for a package, ``category/package: …``; |
184 |
+- for an eclass, ``name.eclass: …``; |
185 |
+- for other directories or files, their path or filename (as long |
186 |
+ as a developer reading the commit messages is able to figure out what |
187 |
+ it is) — e.g. ``licenses/foo: …``, ``package.mask: …``. |
188 |
+ |
189 |
+The body is included in the full commit log (``git log``, detailed |
190 |
+commit info on gitweb/GitHub, mail body). It is optional, and it can be |
191 |
+used to describe the commit in more detail if the summary line is not |
192 |
+sufficient. It is generally a good idea to repeat the information |
193 |
+contained in the summary (except for the logical unit) since the summary |
194 |
+is frequently formatted as a title and not adjacent to the body. |
195 |
+The body should be wrapped at 72 characters. It can contain multiple |
196 |
+paragraphs, separated by empty lines. |
197 |
+ |
198 |
+The tag part is included in the full commit log as an extension to |
199 |
+the body. It consists of one or more lines consisting of a key, |
200 |
+followed by a colon and a space, followed by value. Git does not |
201 |
+enforce any standardization of the keys, and the tag format is *not* |
202 |
+meant for machine processing. |
203 |
+ |
204 |
+A few tags of common use are: |
205 |
+ |
206 |
+- user-related tags: |
207 |
+ |
208 |
+ - ``Acked-by: Full Name <email@×××××××.com>`` — commit approved |
209 |
+ by another person (usually without detailed review), |
210 |
+ - ``Reported-by: Full Name <email@×××××××.com>`` — usually indicates |
211 |
+ full review, |
212 |
+ - ``Signed-off-by: Full Name <email@×××××××.com>`` — DCO approval (not |
213 |
+ used in Gentoo right now), |
214 |
+ - ``Suggested-by: Full Name <email@×××××××.com>``, |
215 |
+ - ``Tested-by: Full Name <email@×××××××.com>``. |
216 |
+ |
217 |
+- commit-related tags: |
218 |
+ |
219 |
+ - ``Fixes: commit-id (commit message)`` — to indicate fixing |
220 |
+ an earlier commit, |
221 |
+ - ``Reverts: commit-id (commit message)`` — to indicate reverting |
222 |
+ an earlier commit, |
223 |
+ |
224 |
+- bug tracker-related tags: |
225 |
+ |
226 |
+ - ``Bug: https://bugs.gentoo.org/NNNNNN`` — to reference a bug; |
227 |
+ the commit will be linked in a comment, |
228 |
+ - ``Closes: https://bugs.gentoo.org/NNNNNN`` — to automatically close |
229 |
+ a Gentoo bug (RESOLVED/FIXED, linking the commit), |
230 |
+ - ``Closes: https://github.com/gentoo/gentoo/pull/NNNN`` — |
231 |
+ to automatically close a pull request on GitHub, GitLab, BitBucket |
232 |
+ or a compatible service (where the commits are mirrored), |
233 |
+ |
234 |
+- package manager tags: |
235 |
+ |
236 |
+ - ``Package-Manager: …`` — used by repoman to indicate Portage |
237 |
+ version, |
238 |
+ - ``RepoMan-Options: …`` — used by repoman to indicate repoman |
239 |
+ options. |
240 |
+ |
241 |
+ |
242 |
+Rationale |
243 |
+========= |
244 |
+ |
245 |
+Branching model |
246 |
+--------------- |
247 |
+The model of multiple developers pushing concurrently to the repository |
248 |
+containing all packages is preserved from CVS. The developers have |
249 |
+discussed the possibility of using other models, in particular of using |
250 |
+multiple branches for developers that are afterwards automatically |
251 |
+merged into the master branch. However, it was determined that there is |
252 |
+no need to use a more complex model at the moment and the potential |
253 |
+problems with them outweighed the benefits. |
254 |
+ |
255 |
+The necessity of rebasing is a natural consequence of concurrent work, |
256 |
+along with the ban of reverse merge commits. Since rebasing a number |
257 |
+of commits can take a few seconds or even more, another developer |
258 |
+sometimes commits during that time, enforcing another rebase. |
259 |
+ |
260 |
+In the past, there were cases of developers using automated scripts |
261 |
+which created single commits, ran repoman and pushed them straight to |
262 |
+the repository. This resulted in pushes from a single developer every |
263 |
+10-15 seconds which made it impossible for other developers to rebase |
264 |
+larger commit batches. This kind of workflow is therefore strongly |
265 |
+discouraged. |
266 |
+ |
267 |
+Creating multiple short-time branches is discouraged as it implies |
268 |
+additional transfer for users cloning the repository and additional |
269 |
+maintenance burden. Since the git migration, the developers have |
270 |
+created a few branches on the repository, and did not maintain them. |
271 |
+The Infra team had to query the developers about the state |
272 |
+of the branches and clean them up. Keeping branches local or hosting |
273 |
+them outside Gentoo Infra (e.g. on GitHub) reduces the burden on our |
274 |
+users, even if the developers do not clean after themselves. |
275 |
+ |
276 |
+ |
277 |
+Merge commits |
278 |
+------------- |
279 |
+Merge commits have been debated multiple times in various media, |
280 |
+in particular IRC. They have very verbose opponents whose main argument |
281 |
+is that they make history unreadable. At the same time, it has been |
282 |
+frequently pointed out that merge commits have valid use cases. |
283 |
+To satisfy both groups, this specification strongly discourages merge |
284 |
+commits but allows their use in justified cases. |
285 |
+ |
286 |
+Most importantly, the implicit merge commits created by ``git pull`` |
287 |
+are forbidden. Those merges have no real value or justified use case, |
288 |
+and since they are created implicitly by default there have been |
289 |
+historical cases where developers pushed them unintentionally. They are |
290 |
+banned explicitly to emphasize the necessity of adjusting git |
291 |
+configuration to the developers. |
292 |
+ |
293 |
+When processing merge commits, it is important to explicitly distinguish |
294 |
+the parent that represents 'real' Gentoo history from the one(s) that |
295 |
+represent external branches. The former can either be an existing |
296 |
+Gentoo commit or a commit that the developer has prepared (on top of |
297 |
+existing Gentoo history) before merging the branch. For this reason, it |
298 |
+is important to enforce the full set of Gentoo policies on this parent |
299 |
+and the commits preceding it. On the other hand, the external branches |
300 |
+can be treated similarly to development branches. Relaxing the rules |
301 |
+for external branches also makes it possible to merge user contributions |
302 |
+with original user OpenPGP signatures, while adding a final developer |
303 |
+signature on top of the merge commit. |
304 |
+ |
305 |
+When using ``git merge foo``, the first parent represents the current |
306 |
+``HEAD`` and the second one the merged branch. This is the model |
307 |
+used by the specification. |
308 |
+ |
309 |
+ |
310 |
+OpenPGP signatures |
311 |
+------------------ |
312 |
+The signature requirements strictly correspond to the git setup deployed |
313 |
+by the Infrastructure team. |
314 |
+ |
315 |
+The commit signatures provide an ability to verify the authenticity |
316 |
+of all commits throughout the Gentoo repository history (to the point |
317 |
+of git conversion). The push signatures mostly serve the purpose |
318 |
+of additional authentication for the developer pushing a specific set |
319 |
+of commits. |
320 |
+ |
321 |
+ |
322 |
+Splitting commits |
323 |
+----------------- |
324 |
+The goal of the commit splitting rules is to make the best use of git |
325 |
+while avoiding enforcing too much overhead on the developer |
326 |
+and optimizing to avoid interim broken commits. |
327 |
+ |
328 |
+Splitting commits by logical changes improves the readability and makes |
329 |
+it easier to revert a specific change while preserving the remaining |
330 |
+(irrelevant) changes. The changes done by a developer are easier |
331 |
+to comprehend when the reviewer can follow them in the specific order |
332 |
+done by the author, rather than combined with other changes. |
333 |
+ |
334 |
+Splitting commits on logical unit boundary was used since CVS times. |
335 |
+Mostly it improves readability via making it possible to include |
336 |
+the unit (package, eclass…) name in the commit message — so that |
337 |
+developers perceive what specific packages are affected by the change |
338 |
+without having to look into diffstat. |
339 |
+ |
340 |
+Requiring commits to be non-'broken' is meant to preserve a good quality |
341 |
+git history of the repository. This means that the users can check |
342 |
+an interim commit out without risking a major problem such as a missing |
343 |
+dependency that is being added by the commit following it. It also |
344 |
+makes it safer to revert the most recent changes with reduced risk |
345 |
+of exposing a breakage. |
346 |
+ |
347 |
+Those rules partially overlap, and if that is the case, the developers |
348 |
+are expected to use common sense to determine the course of action that |
349 |
+gives the best result. Furthermore, requiring the strict following |
350 |
+of the rules would mean a lot of additional work for developers |
351 |
+and a lot of additional commits for no real benefit. |
352 |
+ |
353 |
+The examples are provided to make it possible for the developers to get |
354 |
+a 'feeling' how to work with the rules. |
355 |
+ |
356 |
+ |
357 |
+Commit messages |
358 |
+--------------- |
359 |
+The basic commit message format is similar to the one used by other |
360 |
+projects, and provides for reasonably predictable display of results. |
361 |
+ |
362 |
+The summary line is meant to provide a good concise summary |
363 |
+of the changes. It is included in the short logs, and should include |
364 |
+all the information to help developer determine whether he is interested |
365 |
+in looking into the commit details. Including the logical unit name |
366 |
+accounts for the fact that most of the Gentoo commits are specific |
367 |
+to those units (e.g. packages). The length limit is meant to avoid |
368 |
+wrapping the shortlog — which could result in unreadable ``git log |
369 |
+--oneline`` or ugly mid-word ellipsis on GitHub. |
370 |
+ |
371 |
+The body is meant to provide the detailed information for a commit. |
372 |
+It is usually displayed verbatim, and the use of paragraphs along with |
373 |
+line wrapping is meant to improve readability. The body should include |
374 |
+the information contained in the summary since the two are sometimes |
375 |
+really disjoint, and expecting the user to read body as a continuation |
376 |
+of summary is confusing. For example, in ``git send-email``, |
377 |
+the summary line is used to construct the mail's subject |
378 |
+and is therefore disjoint from the body. |
379 |
+ |
380 |
+The tag section is a traditional way of expressing quasi-machine- |
381 |
+readable data. However, the commit messages are not really suited |
382 |
+for machine use and only a few tags are actually processed by scripts. |
383 |
+The specification tries to provide a concise set of potentially useful |
384 |
+tags collected from various projects (the Linux kernel, X.org). Those |
385 |
+tags can be used interchangeably with plaintext explanation in the body. |
386 |
+ |
387 |
+The only tag defined by git itself is the ``Signed-off-by`` line, |
388 |
+that is created by ``git commit -s``. However, Gentoo does not |
389 |
+currently enforce a DCO consistently, and therefore it is meaningless. |
390 |
+ |
391 |
+The tags subject to machine processing are the ``Bug`` and ``Closes`` |
392 |
+lines. Both are used by git.gentoo.org to handle Gentoo Bugzilla |
393 |
+and the latter is also used by GitHub to automatically close pull |
394 |
+requests (and issues — however, Gentoo does not use GitHub's issue |
395 |
+tracker). GitHub, GitLab, Bitbucket, git.gentoo.org also support |
396 |
+``Fixes`` and ``Resolves`` tags (and the first three also some |
397 |
+variations of them), however ``Closes`` has been already established |
398 |
+in Gentoo and is used for consistency. |
399 |
+ |
400 |
+All the remaining tags serve purely as a user convenience. |
401 |
+ |
402 |
+Historically, Gentoo has been using a few tags starting with ``X-``. |
403 |
+However, this practice was abandoned once it has been pointed out that |
404 |
+git does not enforce any standard set of tags, and therefore indicating |
405 |
+non-standard tags is meaningless. |
406 |
+ |
407 |
+Gentoo developers are still frequently using ``Gentoo-Bug`` tag, |
408 |
+sometimes followed by ``Gentoo-Bug-URL``. Using both |
409 |
+simultaneously is meaningless (they are redundant), and using the former |
410 |
+has no advantages over using the classic ``#nnnnnn`` form in the summary |
411 |
+or the body. |
412 |
+ |
413 |
+Using full URLs in ``Closes`` is necessary to properly namespace |
414 |
+the action to the Gentoo services and avoid accidentally closing |
415 |
+incorrect issues or pull requests when the commit is mirrored or cherry- |
416 |
+picked into another repository. For consistency, they are also used |
417 |
+for ``Bug`` and should be used for any future tags that might be |
418 |
+introduced. This also ensures that the URLs are automatically converted |
419 |
+into hyperlinks by various tools. |
420 |
+ |
421 |
+Including the bug number in the summary of the commit message causes |
422 |
+willikins to automatically expand on the bug on ``#gentoo-commits``. |
423 |
+ |
424 |
+ |
425 |
+Backwards Compatibility |
426 |
+======================= |
427 |
+Most of the new policy will apply to the commits following its approval. |
428 |
+Backwards compatibility is not relevant there. |
429 |
+ |
430 |
+One particular point that affects commits retroactively is the OpenPGP |
431 |
+signing. However, it has been an obligatory requirement enforced by |
432 |
+the infrastructure since the git switch. Therefore, all the git history |
433 |
+conforms to that. |
434 |
+ |
435 |
+ |
436 |
+Reference Implementation |
437 |
+======================== |
438 |
+All of the elements requiring explicit implementation on the git |
439 |
+infrastructure are implemented already. In particular this includes: |
440 |
+ |
441 |
+- blocking force pushes on the ``master`` branch, |
442 |
+- requiring signed commits on the ``master`` branch, |
443 |
+- requiring signed pushes to the repository. |
444 |
+ |
445 |
+The remaining elements are either non-obligatory or non-enforceable |
446 |
+at infrastructure level. |
447 |
+ |
448 |
+RepoMan suggests starting the commit message with package name since |
449 |
+commit 46dafadff58da0 [#REPOMAN_PKG_NAME_COMMIT]_. |
450 |
+ |
451 |
+Acknowledgements |
452 |
+================ |
453 |
+Most of the foundations for this specification were laid out by Julian |
454 |
+Ospald (hasufell) in his initial version of Gentoo git workflow |
455 |
+[#GENTOO_GIT_WORKFLOW]_ article. |
456 |
+ |
457 |
+ |
458 |
+References |
459 |
+========== |
460 |
+.. [#GENTOO_GIT_WORKFLOW] Gentoo Git Workflow (on Gentoo Wiki) |
461 |
+ https://wiki.gentoo.org/wiki/Gentoo_git_workflow |
462 |
+ |
463 |
+.. [#GENTOO_GITHUB] Gentoo GitHub (on Gentoo Wiki) |
464 |
+ https://wiki.gentoo.org/wiki/Gentoo_GitHub |
465 |
+ |
466 |
+.. TODO: verify this |
467 |
+.. [#GLEP63] GLEP 63: Gentoo GPG key policies |
468 |
+ https://www.gentoo.org/glep/glep-0063.html |
469 |
+ |
470 |
+.. [#REPOMAN_PKG_NAME_COMMIT] |
471 |
+ https://gitweb.gentoo.org/proj/portage.git/commit/?id=46dafadff58da0220511f20480b73ad09f913430 |
472 |
+ |
473 |
+ |
474 |
+Copyright |
475 |
+========= |
476 |
+This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 |
477 |
+Unported License. To view a copy of this license, visit |
478 |
+http://creativecommons.org/licenses/by-sa/3.0/. |