1 |
On 7/25/2017 4:05 AM, Michał Górny wrote: |
2 |
> Hi, everyone. |
3 |
> |
4 |
> There have been multiple attempts at grasping this but none so far |
5 |
> resulted in something official and indisputable. At the same time, we |
6 |
> end having to point our users at semi-official guides which change |
7 |
> in unpredictable ways. |
8 |
> |
9 |
> Here's the current draft: |
10 |
> https://wiki.gentoo.org/wiki/User:MGorny/GLEP:Git |
11 |
> |
12 |
> The basic idea is that the GLEP provides basic guidelines for using git, |
13 |
> and then we write a proper manual on top of it (right now, all the pages |
14 |
> about it end up as a mix of requirements and a partial git manual). |
15 |
> |
16 |
> What do you think about it? Is there anything else that needs being |
17 |
> covered? |
18 |
> |
19 |
> Copy of the markup for inline comments follows. |
20 |
|
21 |
[cut] |
22 |
> ===Commit messages=== |
23 |
> A standard git commit message consists of three parts, in order: a |
24 |
> summary line, an optional body and an optional set of tags. The parts |
25 |
> are separated by a single empty line. |
26 |
> |
27 |
[cut] |
28 |
> The tag part is included in the full commit log as an extension to the |
29 |
> body. It consists of one or more lines consisting of key, followed by a |
30 |
> colon and a space, followed by value. Git does not enforce any |
31 |
> standardization of the keys, and the tag format is ''not'' meant for |
32 |
> machine processing. |
33 |
> |
34 |
> A few tags of common use are: |
35 |
> * user-related tags: |
36 |
> ** <kbd>Acked-by: Full Name <email@×××××××.com></kbd> — commit approved |
37 |
> by another person (usually without detailed review), |
38 |
> ** <kbd>Reported-by: Full Name <email@×××××××.com></kbd>, |
39 |
> ** <kbd>Reviewed-by: Full Name <email@×××××××.com></kbd> — usually |
40 |
> indicates full review, |
41 |
> ** <kbd>Signed-off-by: Full Name <email@×××××××.com></kbd> — DCO |
42 |
> approval (not used in Gentoo right now), |
43 |
> ** <kbd>Suggested-by: Full Name <email@×××××××.com></kbd>, |
44 |
> ** <kbd>Tested-by: Full Name <email@×××××××.com></kbd>. |
45 |
> * commit-related tags: |
46 |
> ** <kbd>Fixes: commit-id (commit message)</kbd> — to indicate fixing a |
47 |
> previous commit, |
48 |
> ** <kbd>Reverts: commit-id (commit message)</kbd> — to indicate |
49 |
> reverting a previous commit, |
50 |
> * bug tracker-related tags: |
51 |
> ** <kbd>Bug: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — to |
52 |
> reference a bug, |
53 |
> ** <kbd>Closes: <nowiki>https://github.com/gentoo/gentoo/pull/NNNN</nowi |
54 |
> ki></kbd>; — to automatically close a GitHub pull request, |
55 |
> ** <kbd>Fixes: <nowiki>https://bugs.gentoo.org/NNNNNN</nowiki></kbd>; — |
56 |
> to indicate a fixed bug, |
57 |
> * package manager tags: |
58 |
> ** <kbd>Package-Manager: …</kbd> — used by repoman to indicate Portage |
59 |
> version, |
60 |
> ** <kbd>RepoMan-Options: …</kbd> — used by repoman to indicate repoman |
61 |
> options. |
62 |
> |
63 |
> The bug tracker-related tags can be used to extend the body message. |
64 |
> However, they should be skipped if the bug number is already provided in |
65 |
> the summary and there is no explicit body. |
66 |
> |
67 |
|
68 |
My concern on these tags is that some evangelist will come along and |
69 |
demand that they always be included with every commit since they exist |
70 |
in a GLEP. They add very little value, IMO, and I doubt they will ever |
71 |
be parsed or ever read. |
72 |
|
73 |
I would object less if the committing tool, i.e. repoman, would provide |
74 |
easy switches for common cases for uniformity. I foresee more work on |
75 |
my part to remember such lines and would have to look up the "current |
76 |
syntax" as it goes through debate many times over as it already has. |
77 |
(Both in the past and in this thread again). |
78 |
|
79 |
Brian |