Re: git commit messages
2009/4/22 Vincent Untz vu...@gnome.org: Hey, - First line (the brief description) must only be one sentence and should start with a capital letter unless it starts with a lowercase symbol or identifier. Don't use a trailing period either. Don't exceed 72 characters. Hey, Sorry for revamping an old thread but I kept wondering why vim highlighted only first 50 characters of my subject lines, so I checked git-commit manpage. It suggests less than 50 characters for the first line, is there any particular reason why we shouldn't follow git guidelines? - When committing code on behalf of others use the --author option, e.g. git commit -a --author Joe Coder j...@coder.org and --signoff. A mention for git-format-patch + git-am workflow could be worth here. Filippo ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Wed, Apr 22, 2009 at 10:10 PM, Behdad Esfahbod beh...@behdad.org wrote: Another option I like to document if we can agree on is prefixing the short-summary with a tag, like for example: [layout] Improve X or Y Others suggested: layout: Improve X or Y I prefer the former as it's visually more pleasing to me AND visually easier to recognize the tag in git-shortlog output. In git.git they prefer layout: improve X or Y (no capital letter). -- Felipe Contreras ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Thu, Apr 23, 2009 at 7:09 PM, Shaun McCance sha...@gnome.org wrote: On Thu, 2009-04-23 at 11:45 +0200, Murray Cumming wrote: On Wed, 2009-04-22 at 16:46 +0200, Vincent Untz wrote: Don't use a trailing period either. I find this really odd and rather arbitrary. I think it's something to do with you wanting to use these first lines in bullet-point lists. But there's no real grammar consensus about periods at the end of bullet-point items. I personally can't stand a sentence without a bullet point if it's more than 4 or 5 words. Can we please remove that requirement? It's not a requirement. It's a suggestion. Individual maintainers are free to have different suggestions. So the goal of the overall suggestions is to capture what most maintainers want. Exactly, it's a guideline. Personally I don't see the point of a full-stop; you already know the summary will be one line, and if for some reason is not complete you'll see ... -- Felipe Contreras ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Wed, Apr 22, 2009 at 6:09 PM, Christophe Fergeau t...@gnome.org wrote: Hi Vincent, 2009/4/22 Vincent Untz vu...@gnome.org - When committing code on behalf of others use the --author option, e.g. git commit -a --author Joe Coder j...@coder.org and --signoff. Opinions? Not sure about the --signoff part. The committer email/name is already silently added to the commit by git even when using --author. Moreover, When reading the 12) Sign your work section of SubmittingPatches from the linux kernel source ( http://lxr.linux.no/linux/Documentation/SubmttingPatches ), it seems to me that using SignedOffBy is useless if the initial author of the patch didn't use it : The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. (snipped a lot of explanations after this sentence) s-o-b lines are useful if you are following a chain-of-trust model. If you wrote the patch, you add your s-o-b, if you reviewed the patch and think it's ok, then you add your s-o-b too. The commit that goes into the main repo will end up having multiple s-o-b lines and if something goes wrong all the people in the s-o-b are to blame. If you commit a patch without reviewing it fully, then don't add your s-o-b. In a distributed model the s-o-b lines help people to decide whether or not to pick commits from other repositories or a mailing list. The more distributed, the more you need s-o-b lines. In GNOME perhaps the needs doesn't seem too high right now, but think about a patch that was developed collaboratively by 4, or 5 people. A single 'committer' and 'author' field is not enough to represent what really happened. -- Felipe Contreras ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
Le mercredi 22 avril 2009, à 16:46 +0200, Vincent Untz a écrit : We can copy paste it to http://live.gnome.org/Git/CommitMessages if people agree. I created this, with a few changes: + removed mention of --signoff + add tag on first line of commit message (as suggested by Behdad) + mention that the main description can be empty if it's trivial (as suggested by Behdad) Vincent -- Les gens heureux ne sont pas pressés. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
Le mercredi 22 avril 2009, à 07:55 -0700, Sandy Armstrong a écrit : I agree. And either Git/Developers should be expanded to include all these details, or its commit message section should link to Git/CommitMessages. I changed the section to link to Git/CommitMessages. Vincent -- Les gens heureux ne sont pas pressés. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Thu, 2009-04-23 at 11:45 +0200, Murray Cumming wrote: On Wed, 2009-04-22 at 16:46 +0200, Vincent Untz wrote: Don't use a trailing period either. I find this really odd and rather arbitrary. I think it's something to do with you wanting to use these first lines in bullet-point lists. But there's no real grammar consensus about periods at the end of bullet-point items. I personally can't stand a sentence without a bullet point if it's more than 4 or 5 words. Can we please remove that requirement? It's not a requirement. It's a suggestion. Individual maintainers are free to have different suggestions. So the goal of the overall suggestions is to capture what most maintainers want. FWIW, the no-period form matches exactly what we do for application descriptions in .desktop files, as well as the module descriptions in the new DOAP files. I don't think our Style Guide has anything to say on this matter. We do generally defer to CMS. I could check if CMS says anything if anybody wants to get really persnickety about grammar. Personally, and this is coming from the documentation guy, I think it's pretty massive non-issue. -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On 04/23/2009 08:47 AM, Loïc Minier wrote: On Wed, Apr 22, 2009, Vincent Untz wrote: Frédéric (fredp) is suggesting to also propose a standard scheme to reference bugs that are fixed by a commit (so we can script things if it's needed one day -- that's similar to what Debian does). Something like Closes: #123456 or Fixes: #123456. This should probably live in the longer explanation since the short explanation is limited in size... (Then we can also reference other bug trackers when needed: bnc#12345, rh#12345, lp#12345, etc.) That would be excellent, thanks! However please consider using: GNOME #1234 one issue with the Debian closes: is that it doesn't indicate Debian, which is why Nokia, Ubuntu etc. all use different prefixes to refer to their bugs. Using GNOME #1234 would allow terminals to link to bugzilla.gnome.org directly for instance. I prefer the more verbose GNOME Bug #1234 in that case. And I opened a bug yesterday to allow configuring such matchers on gnome-terminal: http://bugzilla.gnome.org/show_bug.cgi?id=579859 behdad ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
Le jeudi 23 avril 2009, à 15:42 -0400, Behdad Esfahbod a écrit : On 04/23/2009 08:47 AM, Loïc Minier wrote: On Wed, Apr 22, 2009, Vincent Untz wrote: Frédéric (fredp) is suggesting to also propose a standard scheme to reference bugs that are fixed by a commit (so we can script things if it's needed one day -- that's similar to what Debian does). Something like Closes: #123456 or Fixes: #123456. This should probably live in the longer explanation since the short explanation is limited in size... (Then we can also reference other bug trackers when needed: bnc#12345, rh#12345, lp#12345, etc.) That would be excellent, thanks! However please consider using: GNOME #1234 one issue with the Debian closes: is that it doesn't indicate Debian, which is why Nokia, Ubuntu etc. all use different prefixes to refer to their bugs. Using GNOME #1234 would allow terminals to link to bugzilla.gnome.org directly for instance. I prefer the more verbose GNOME Bug #1234 in that case. But I'm lazy. You'll likely get me to write bgo#1234 or gnome#1234, but writing GNOME Bug #1234 or Novell Bug #1234, Red Hat Bug #1234... it just won't work for me (and I would guess other people). Vincent -- Les gens heureux ne sont pas pressés. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Thu, 2009-04-23 at 21:59 +0200, Vincent Untz wrote: Le jeudi 23 avril 2009, à 15:42 -0400, Behdad Esfahbod a écrit : On 04/23/2009 08:47 AM, Loïc Minier wrote: On Wed, Apr 22, 2009, Vincent Untz wrote: Frédéric (fredp) is suggesting to also propose a standard scheme to reference bugs that are fixed by a commit (so we can script things if it's needed one day -- that's similar to what Debian does). Something like Closes: #123456 or Fixes: #123456. This should probably live in the longer explanation since the short explanation is limited in size... (Then we can also reference other bug trackers when needed: bnc#12345, rh#12345, lp#12345, etc.) That would be excellent, thanks! However please consider using: GNOME #1234 one issue with the Debian closes: is that it doesn't indicate Debian, which is why Nokia, Ubuntu etc. all use different prefixes to refer to their bugs. Using GNOME #1234 would allow terminals to link to bugzilla.gnome.org directly for instance. I prefer the more verbose GNOME Bug #1234 in that case. But I'm lazy. You'll likely get me to write bgo#1234 or gnome#1234, but writing GNOME Bug #1234 or Novell Bug #1234, Red Hat Bug #1234... it just won't work for me (and I would guess other people). I have a certain fondness for http://bugzilla.gnome.org/show_bug.cgi?id=1234 Not that I want to *type* that but I can be ultimately lazy and cut-and-paste it in without fear of mistyping the bug number. - Owen [ Yes, it's not very compact ] ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Thu, 2009-04-23 at 16:23 -0400, Owen Taylor wrote: On Thu, 2009-04-23 at 21:59 +0200, Vincent Untz wrote: Le jeudi 23 avril 2009, à 15:42 -0400, Behdad Esfahbod a écrit : On 04/23/2009 08:47 AM, Loïc Minier wrote: On Wed, Apr 22, 2009, Vincent Untz wrote: Frédéric (fredp) is suggesting to also propose a standard scheme to reference bugs that are fixed by a commit (so we can script things if it's needed one day -- that's similar to what Debian does). Something like Closes: #123456 or Fixes: #123456. This should probably live in the longer explanation since the short explanation is limited in size... (Then we can also reference other bug trackers when needed: bnc#12345, rh#12345, lp#12345, etc.) That would be excellent, thanks! However please consider using: GNOME #1234 one issue with the Debian closes: is that it doesn't indicate Debian, which is why Nokia, Ubuntu etc. all use different prefixes to refer to their bugs. Using GNOME #1234 would allow terminals to link to bugzilla.gnome.org directly for instance. I prefer the more verbose GNOME Bug #1234 in that case. But I'm lazy. You'll likely get me to write bgo#1234 or gnome#1234, but writing GNOME Bug #1234 or Novell Bug #1234, Red Hat Bug #1234... it just won't work for me (and I would guess other people). I have a certain fondness for http://bugzilla.gnome.org/show_bug.cgi?id=1234 Not that I want to *type* that but I can be ultimately lazy and cut-and-paste it in without fear of mistyping the bug number. - Owen [ Yes, it's not very compact ] But it's certainly the easiest to parse for any crazy kids out there who like building project trackers. -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Wed, Apr 22, 2009 at 7:46 AM, Vincent Untz vu...@gnome.org wrote: Hey, The GTK+ team documented how they'd like to see the git commit messages in http://git.gnome.org/cgit/gtk+/tree/README.commits = copy paste = The expected format for git commit messages is as follows: === begin example commit === Short explanation of the commit Longer explanation explaining exactly what's changed, whether any external or private interfaces changed, what bugs were fixed (with bug tracker reference if applicable) and so forth. Be concise but not too brief. === end example commit === - Always add a brief description of the commit to the _first_ line of the commit and terminate by two newlines (it will work without the second newline, but that is not nice for the interfaces). - First line (the brief description) must only be one sentence and should start with a capital letter unless it starts with a lowercase symbol or identifier. Don't use a trailing period either. Don't exceed 72 characters. - The main description (the body) is normal prose and should use normal punctuation and capital letters where appropriate. Normally, for patches sent to a mailing list it's copied from there. - When committing code on behalf of others use the --author option, e.g. git commit -a --author Joe Coder j...@coder.org and --signoff. I'd like to suggest that this is the default recommendation for GNOME modules, since having some common guidelines will make the life easier for most people. If some maintainers disagree, they can of course ask for something else in their modules. We can copy paste it to http://live.gnome.org/Git/CommitMessages if people agree. I agree. And either Git/Developers should be expanded to include all these details, or its commit message section should link to Git/CommitMessages. Sandy ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On Wed, Apr 22, 2009 at 4:09 PM, Christophe Fergeau t...@gnome.org wrote: Hi Vincent, 2009/4/22 Vincent Untz vu...@gnome.org - When committing code on behalf of others use the --author option, e.g. git commit -a --author Joe Coder j...@coder.org and --signoff. Opinions? Not sure about the --signoff part. The committer email/name is already silently added to the commit by git even when using --author. Moreover, When reading the 12) Sign your work section of SubmittingPatches from the linux kernel source ( http://lxr.linux.no/linux/Documentation/SubmttingPatches ), it seems to me that using SignedOffBy is useless if the initial author of the patch didn't use it : The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. (snipped a lot of explanations after this sentence) There was a recent discussion on this, http://mail.gnome.org/archives/gnome-infrastructure/2009-April/msg00011.html Simos ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
Vincent Untz wrote: Frédéric (fredp) is suggesting to also propose a standard scheme to reference bugs that are fixed by a commit (so we can script things if it's needed one day -- that's similar to what Debian does). Something like Closes: #123456 or Fixes: #123456. I think KDE uses something similar to automatically close bugzilla bugs using a hook script. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
Le mercredi 22 avril 2009, à 16:46 +0200, Vincent Untz a écrit : Hey, The GTK+ team documented how they'd like to see the git commit messages in http://git.gnome.org/cgit/gtk+/tree/README.commits = copy paste = The expected format for git commit messages is as follows: === begin example commit === Short explanation of the commit Longer explanation explaining exactly what's changed, whether any external or private interfaces changed, what bugs were fixed (with bug tracker reference if applicable) and so forth. Be concise but not too brief. === end example commit === - Always add a brief description of the commit to the _first_ line of the commit and terminate by two newlines (it will work without the second newline, but that is not nice for the interfaces). - First line (the brief description) must only be one sentence and should start with a capital letter unless it starts with a lowercase symbol or identifier. Don't use a trailing period either. Don't exceed 72 characters. - The main description (the body) is normal prose and should use normal punctuation and capital letters where appropriate. Normally, for patches sent to a mailing list it's copied from there. - When committing code on behalf of others use the --author option, e.g. git commit -a --author Joe Coder j...@coder.org and --signoff. Frédéric (fredp) is suggesting to also propose a standard scheme to reference bugs that are fixed by a commit (so we can script things if it's needed one day -- that's similar to what Debian does). Something like Closes: #123456 or Fixes: #123456. This should probably live in the longer explanation since the short explanation is limited in size... (Then we can also reference other bug trackers when needed: bnc#12345, rh#12345, lp#12345, etc.) Vincent -- Les gens heureux ne sont pas pressés. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
Hi Vincent, 2009/4/22 Vincent Untz vu...@gnome.org - When committing code on behalf of others use the --author option, e.g. git commit -a --author Joe Coder j...@coder.org and --signoff. Opinions? Not sure about the --signoff part. The committer email/name is already silently added to the commit by git even when using --author. Moreover, When reading the http://lxr.linux.no/linux+v2.6.29/Documentation/SubmittingPatches#L28212) Sign your work section of SubmittingPatches from the linux kernel source ( http://lxr.linux.no/linux/Documentation/SubmttingPatches ), it seems to me that using SignedOffBy is useless if the initial author of the patch didn't use it : The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to http://lxr.linux.no/linux+v2.6.29/Documentation/SubmittingPatches#L291pass it on as a open-source patch. (snipped a lot of explanations after this sentence) Cheers, Christophe ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: git commit messages
On 04/22/2009 10:46 AM, Vincent Untz wrote:
I'd like to suggest that this is the default recommendation for GNOME
modules, since having some common guidelines will make the life easier
for most people. If some maintainers disagree, they can of course ask
for something else in their modules.
+1.
We can copy paste it to http://live.gnome.org/Git/CommitMessages if
people agree.
Yes please.
Opinions?
I also like to mention that one-liners are also acceptable if the change is
really self-explanatory. Like, say Fix leak. There's not much more to say.
Another option I like to document if we can agree on is prefixing the
short-summary with a tag, like for example:
[layout] Improve X or Y
Others suggested:
layout: Improve X or Y
I prefer the former as it's visually more pleasing to me AND visually easier
to recognize the tag in git-shortlog output.
In another mail you wrote:
Frédéric (fredp) is suggesting to also propose a standard scheme to
reference bugs that are fixed by a commit (so we can script things if
it's needed one day -- that's similar to what Debian does).
Something like Closes: #123456 or Fixes: #123456.
This should probably live in the longer explanation since the short
explanation is limited in size...
I don't quite like something like this. I use the much more verbose version
in my commits. In fact, sometimes I use the bug title like as my short
summary. Like:
commit 2fc08eeb9daeabd9fbac1e8ae409581117601bb5
Author: Behdad Esfahbod beh...@behdad.org
Date: Thu Apr 9 13:30:26 2009 -0400
Bug 577952 – Error loading {GDEF,GSUB,GPOS} table 0x6EAD
Detect TrueType Collections by checking the font data header instead
of checking for face-num_faces 1.
If I need to, I change the bug title first to make it accurate.
(Then we can also reference other bug trackers when needed: bnc#12345,
rh#12345, lp#12345, etc.)
Why so cryptic if it's on the long description? I write Red Hat Bug #12345.
I don't know what bnc is for example.
Vincent
behdad
___
desktop-devel-list mailing list
desktop-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/desktop-devel-list
