| 1 |
On Sat, 06 Apr 2013 13:00:35 -0700 |
| 2 |
""Paweł Hajdan, Jr."" <phajdan.jr@g.o> wrote: |
| 3 |
|
| 4 |
> On 4/6/13 12:41 PM, Michał Górny wrote: |
| 5 |
> > I would honestly just go for the git style. It's the first thing that |
| 6 |
> > really succeeded in standardizing patches. Inventing something new is |
| 7 |
> > not really necessary, I believe. |
| 8 |
> |
| 9 |
> Oh, I didn't mean inventing anything new. |
| 10 |
> |
| 11 |
> Is there some URL or documentation I could read to familiarize myself |
| 12 |
> with all of the "git style"? |
| 13 |
|
| 14 |
Hmm, it seems that there is nothing really common, just various things |
| 15 |
that were used and started to be expected by random tools. Except for |
| 16 |
bits of notes in git manpages, there's some info in the 'submitting |
| 17 |
patches' doc [1]. |
| 18 |
|
| 19 |
The general idea is similar to the e-mail concept. Shortly saying, it's: |
| 20 |
|
| 21 |
One line of topic |
| 22 |
|
| 23 |
Paragraph of text, usually wrapped at 72 chars....................... |
| 24 |
Second line of the same paragraph, etcetera. |
| 25 |
|
| 26 |
Second paragraph. Then we'll have a list: |
| 27 |
|
| 28 |
- item 1 |
| 29 |
|
| 30 |
- item 2 |
| 31 |
|
| 32 |
Some-tags: ... |
| 33 |
Other-tag: ... |
| 34 |
|
| 35 |
(indent added to mail to make it clear, no indent in patch file :)) |
| 36 |
|
| 37 |
Although git itself rather preserves newlines, some tool concatenate |
| 38 |
successive lines, so you separate paragraphs (and items) with empty |
| 39 |
lines. |
| 40 |
|
| 41 |
First paragraph (some tools may read one line only!) goes as a short |
| 42 |
summary, that is shown in 'git log --oneline'. The following paragraphs |
| 43 |
(optional) should explain better what's happening. |
| 44 |
|
| 45 |
Optionally, after the last paragraph you can add a few lines with tags |
| 46 |
in form of 'Tag: value'. AFAICS git itself uses only |
| 47 |
'Signed-off-by' but you can find more tags in various 'submitting |
| 48 |
patches' docs. |
| 49 |
|
| 50 |
'Signed-off-by' lists the one responsible for the patch. Some upstreams |
| 51 |
require that line, some take over authorship of patches if you don't |
| 52 |
add it (like X.org), some just hate it :). |
| 53 |
|
| 54 |
The X.org wiki lists also 'Fixes' for bugtracker URL [2] and a few tags |
| 55 |
for reviewing patches [3] (those are probably not useful for us). |
| 56 |
|
| 57 |
Some upstreams also use different bugtracker tag formats [4,5] but I |
| 58 |
feel like they're not proper for our patches since they don't mention |
| 59 |
the bugtracker URI. That said, I'd probably ping them about it. |
| 60 |
|
| 61 |
[1]:http://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches |
| 62 |
[2]:http://www.x.org/wiki/Development/Documentation/SubmittingPatches#Commit_message_format |
| 63 |
[3]:http://www.x.org/wiki/Development/Documentation/SubmittingPatches#Signing_off_and_reviewing |
| 64 |
[4]:http://www.mediawiki.org/wiki/Gerrit/Commit_message_guidelines |
| 65 |
[5]:https://wiki.openstack.org/wiki/GitCommitMessages#Including_external_references |
| 66 |
|
| 67 |
-- |
| 68 |
Best regards, |
| 69 |
Michał Górny |
Archives