[gentoo-dev] Proper commit messages

[gentoo-dev] Proper commit messages

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 2782 bytes --]

Well, you'd think that doing main tree CVS commit messages would be
something that everyone could do properly without being told, but sadly
this doesn't seem to be the case. Soooo...

Believe it or not, commit messages are not just something that you type
in to keep a computer happy. These messages are also read by QA and arch
people.

If you're not a QA or arch person, and you don't consider spending a few
moments to make life easier for those people to be sufficient reason,
you might want to consider that repeated ``cvs diff`` runs will hit the
CVS server far more than one ``cvs log``.

If you're the sort that writes good ChangeLog messages anyway, there's
nothing wrong with reusing them as the commit message. If you have a
really really good reason for not using a ChangeLog message, or if you
haven't yet written a shell alias for reusing ChangeLog messages for
commits, you still need to come up with something for the commit
message.

Your commit message should explain what specifically you changed and, if
relevant, why. You don't need to write an essay or even a complete
sentence (ChangeLog messages, however, *are* required to be in 'proper'
English), so long as it is easily understandable and (preferably)
greppable. Examples, all of which are based upon real messages:

BAD:  Changed keywords
GOOD: Added ~x86 keyword

BAD:  Stable
GOOD: Stable on x86, sparc, mips

BAD:  Fix stuff
GOOD: Fix USE=foo logic error

BAD:  .
GOOD: Purge old ebuilds

BAD:  Vérifiez que le frozbinateur n'est pas cassé.
GOOD: Added a check for broken frozbinator.

BAD:  Who the fuck reads these anyway?
GOOD: Version bump.

Whilst I'm at it, I might as well comment on some things that are useful
in ChangeLogs that don't always get done properly:

* Any relevant bug numbers, formatted like "bug #20600". The # is
  important, it's used by various things (eg packages.g.o) that
  automagically add links to text.

* What that patch you're adding actually does.

* The archs you're working with when keywording. "Marked stable" is a
  nuisance for arch people, even if there was only one keyword in the
  ebuild at the time. "Stable on all archs" isn't generally any better
  (and should you really be stabling on all archs?) -- do you mean
  "all", or "all the ones that are currently keyworded"? A list like
  "x86 sparc mips" is much more useful.

This rant was not inspired by someone committing a bunch of things with
one character (and a punctuation character at that) commit messages
despite repeatedly having been asked not to. Honest.

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Markus Rothe]

[-- Attachment #1: Type: text/plain, Size: 661 bytes --]

Ciaran McCreesh wrote:
> If you're the sort that writes good ChangeLog messages anyway, there's
> nothing wrong with reusing them as the commit message. If you have a
> really really good reason for not using a ChangeLog message, or if you
> haven't yet written a shell alias for reusing ChangeLog messages for
> commits, you still need to come up with something for the commit
> message.

Personaly I find it a little bit annoying to write changes twise. One
time in Changelog and one time in --commitmsg. How about using the
commitmsg for Changelog as default, but if a Changelog entry already
exists, then write nothing to Changelog.

Regards,

Markus Rothe

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Simon Stelling]

Markus Rothe wrote:
> Personaly I find it a little bit annoying to write changes twise. One
> time in Changelog and one time in --commitmsg. How about using the
> commitmsg for Changelog as default, but if a Changelog entry already
> exists, then write nothing to Changelog.

#!/bin/bash
echangelog "${1}"
repoman scan
repoman commit -m "${1}"

-- 
Simon Stelling
Gentoo/AMD64 Operational Co-Lead
blubb@gentoo.org
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Proper commit messages

[Stephen Bennett]

On Tue, 9 Aug 2005 11:36:18 +0000
Markus Rothe <corsair@gentoo.org> wrote:

> Personaly I find it a little bit annoying to write changes twise. One
> time in Changelog and one time in --commitmsg. How about using the
> commitmsg for Changelog as default, but if a Changelog entry already
> exists, then write nothing to Changelog.

I'm sure you can manage to write a bash function to call echangelog and
repoman commit with the same message.
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Proper commit messages

[Markus Rothe]

[-- Attachment #1: Type: text/plain, Size: 768 bytes --]

Stephen Bennett wrote:
> On Tue, 9 Aug 2005 11:36:18 +0000
> Markus Rothe <corsair@gentoo.org> wrote:
> 
> > Personaly I find it a little bit annoying to write changes twise. One
> > time in Changelog and one time in --commitmsg. How about using the
> > commitmsg for Changelog as default, but if a Changelog entry already
> > exists, then write nothing to Changelog.
> 
> I'm sure you can manage to write a bash function to call echangelog and
> repoman commit with the same message.

Sure, I can and the other mail shows that it is *realy* simple, but why
should every dev write his own "script", when this could be done once
for all?

Nevermind.. If I don't provide patches for repoman I shouldn't bitching
around! ;-)

Regards,

Markus Rothe

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 654 bytes --]

On Tuesday 09 August 2005 13:55, Simon Stelling wrote:
> #!/bin/bash
> echangelog "${1}"
> repoman scan
> repoman commit -m "${1}"

Even simpler, as repoman commit abort in case of errors in repoman scan:

ecommit() {
        echangelog "$@"
        repoman commit -m "$@"
}

add that to your .bashrc.

I use it always:

ecommit "Stable on amd64"

and it's done :)
If something is bad, it stops me.
If the package is mine and I want to have it clear, repoman full before 
ecommit to be safe.

-- 
Diego "Flameeyes" Pettenò
Gentoo Developer - http://dev.gentoo.org/~flameeyes/
(Gentoo/FreeBSD, Video, Gentoo/AMD64, Sound, PAM)

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 1253 bytes --]

On Tue, 9 Aug 2005 12:23:20 +0000 Markus Rothe <corsair@gentoo.org>
wrote:
| Stephen Bennett wrote:
| > On Tue, 9 Aug 2005 11:36:18 +0000
| > Markus Rothe <corsair@gentoo.org> wrote:
| > 
| > > Personaly I find it a little bit annoying to write changes twise.
| > > One time in Changelog and one time in --commitmsg. How about
| > > using the commitmsg for Changelog as default, but if a Changelog
| > > entry already exists, then write nothing to Changelog.
| > 
| > I'm sure you can manage to write a bash function to call echangelog
| > and repoman commit with the same message.
| 
| Sure, I can and the other mail shows that it is *realy* simple, but
| why should every dev write his own "script", when this could be done
| once for all?

Isn't this one of those things that's best done on a per-dev basis?
It's so trivial there's no point shipping an app that does it --
reading the associated documentation would take longer than writing
your own. Plus that way you can incorporate personalised clever things
such as auto keyword messages for arch teams

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Markus Rothe]

[-- Attachment #1: Type: text/plain, Size: 403 bytes --]

Ciaran McCreesh wrote:
> Isn't this one of those things that's best done on a per-dev basis?
> It's so trivial there's no point shipping an app that does it --
> reading the associated documentation would take longer than writing
> your own. Plus that way you can incorporate personalised clever things
> such as auto keyword messages for arch teams

Ok. That are good aguments.

Regards,

Markus Rothe

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Jonathan Smith]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ciaran McCreesh wrote:
> Isn't this one of those things that's best done on a per-dev basis?
> It's so trivial there's no point shipping an app that does it --
> reading the associated documentation would take longer than writing
> your own. Plus that way you can incorporate personalised clever things
> such as auto keyword messages for arch teams

i do have one suggestion for every dev who's ever gotten minor syntax -
trailing whitespace errors (somehow that happens to me ALOT)...

#! /bin/bash
sed -e 's/[ \t]*$//' -i *.ebuild || exit 1
# insert the rest of the script here

- --

smithj

Gentoo Developer
[ desktop stuff && network monitoring && documentation ]

Every email I send is digitally signed with OpenPGP key ID 33E2528C, available
from pgp.mit.edu


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFC+P7kl5AvwDPiUowRAlerAJ47id+6CpIIQynuNF2HHrHh86nDPACgxAew
utFPWhf6ix7FKgZYTIt2lAU=
=g/IL
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Proper commit messages

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 508 bytes --]

On Tue, 09 Aug 2005 15:07:16 -0400 Jonathan Smith <smithj@gentoo.org>
wrote:
| i do have one suggestion for every dev who's ever gotten minor syntax
| - trailing whitespace errors (somehow that happens to me ALOT)...

Or use vim, and :set list listchars=tab:»·,trail:·,extends:… , and then
you'll be able to see them visibly.

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Henrik Brix Andersen]

[-- Attachment #1: Type: text/plain, Size: 411 bytes --]

On Tue, 2005-08-09 at 20:22 +0100, Ciaran McCreesh wrote:
> Or use vim, and :set list listchars=tab:»·,trail:·,extends:… , and then
> you'll be able to see them visibly.

Or use a proper editor and do the following ;)


(global-font-lock-mode t)
(setq-default show-trailing-whitespace t)


Regards,
Brix
-- 
Henrik Brix Andersen <brix@gentoo.org>
Gentoo Metadistribution | Mobile computing herd

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Proper commit messages

[Tuan Van]

Ciaran McCreesh wrote:
> On Tue, 09 Aug 2005 15:07:16 -0400 Jonathan Smith <smithj@gentoo.org>
> wrote:
> | i do have one suggestion for every dev who's ever gotten minor syntax
> | - trailing whitespace errors (somehow that happens to me ALOT)...
> 
> Or use vim, and :set list listchars=tab:»·,trail:·,extends:… , and then
> you'll be able to see them visibly.
> 

and for those of us (nano users) ;)
# nano -w /etc/nanorc
set whitespace "»·"
syntax "ebuild" "\.e(build|class)$"
color brightred ".*[[:blank:]]$"
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: Proper commit messages

[Arnaud Launay]

Le Tue, Aug 09, 2005 at 03:54:34PM -0700, Tuan Van a écrit:
> and for those of us (nano users) ;)

BTW, I never understood why it was nano which is on the CD, and
not some vi... ?

	Arnaud.
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Proper commit messages

[LostSon]

[-- Attachment #1: Type: text/plain, Size: 428 bytes --]

On Wed, 2005-08-10 at 01:31 +0200, Arnaud Launay wrote:
> Le Tue, Aug 09, 2005 at 03:54:34PM -0700, Tuan Van a écrit:
> > and for those of us (nano users) ;)
> 
> BTW, I never understood why it was nano which is on the CD, and
> not some vi... ?

 Because most noobies wouldnt have a clue how to use vi
> 
> 	Arnaud.
-- 
LostSon

http://www.lostsonsvault.org

Fox Cities Linux User Group = http://www.foxlug.org

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: Proper commit messages

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 596 bytes --]

On Wed, 10 Aug 2005 01:31:48 +0200 Arnaud Launay <asl@launay.org> wrote:
| Le Tue, Aug 09, 2005 at 03:54:34PM -0700, Tuan Van a écrit:
| > and for those of us (nano users) ;)
| 
| BTW, I never understood why it was nano which is on the CD, and
| not some vi... ?

Executive order from Daniel a long time ago. It's right up there with
"why are we indenting with four wide tabs?" on the "will never be
changed" list.

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: Proper commit messages

[Mike Frysinger]

On Tuesday 09 August 2005 07:31 pm, Arnaud Launay wrote:
> Le Tue, Aug 09, 2005 at 03:54:34PM -0700, Tuan Van a écrit:
> > and for those of us (nano users) ;)
>
> BTW, I never understood why it was nano which is on the CD, and
> not some vi... ?

last i checked, both vi and nano are on livecds now
-mike

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Proper commit messages

[Mike Frysinger]

On Tuesday 09 August 2005 07:40 pm, Ciaran McCreesh wrote:
> On Wed, 10 Aug 2005 01:31:48 +0200 Arnaud Launay <asl@launay.org> wrote:
> | Le Tue, Aug 09, 2005 at 03:54:34PM -0700, Tuan Van a écrit:
> | > and for those of us (nano users) ;)
> |
> | BTW, I never understood why it was nano which is on the CD, and
> | not some vi... ?
>
> Executive order from Daniel a long time ago. It's right up there with
> "why are we indenting with four wide tabs?" on the "will never be
> changed" list.

that may be, but removing nano from the livecd would be stupid ... vi isnt 
n00b friendly in the least

also, four tabs rule
-mike

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Proper commit messages

[Alin Nastac]

[-- Attachment #1: Type: text/plain, Size: 108 bytes --]

Mike Frysinger wrote:

>also, four tabs rule
>
>  
>
you are obviously wrong. three is the magic number ;)


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-dev] Re: Proper commit messages

[Dice R. Random]

On 8/10/05, Alin Nastac <mrness@gentoo.org> wrote:
> Mike Frysinger wrote:
> 
> >also, four tabs rule
> >
> >
> >
> you are obviously wrong. three is the magic number ;)
> 

Who cares as long as they're tabs?

:set ts=3

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Proper commit messages

[Drake Wyrm]

Mike Frysinger <vapier@gentoo.org> wrote:
> also, four tabs rule

I prefer single-character tabs. (0x09)

-- 
I used to think romantic love was a neurosis shared by two, a supreme
foolishness. I no longer thought that. There's nothing foolish in loving
anyone. Thinking you'll be loved in return is what's foolish.
  -- Rita Mae Brown
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Proper commit messages

[Aron Griffis]

[-- Attachment #1: Type: text/plain, Size: 1954 bytes --]

Markus Rothe wrote:	[Tue Aug 09 2005, 07:36:18AM EDT]
> Personaly I find it a little bit annoying to write changes twise.
> One time in Changelog and one time in --commitmsg. How about using
> the commitmsg for Changelog as default, but if a Changelog entry
> already exists, then write nothing to Changelog.

A few others have posted their solutions to this problem.  Perhaps
some people will find my solution useful, since it's a bit more
sophisticated.  I've been using this for literally years now with no
modifications.

    - handles using editor for echangelog
    - fixes spacing before re-using the message for cvs commit
    - post-runs eviewcvs (for the sake of pasting into bugs)

# echangelog and repoman combined
er() {
  echangelog ${1:+"$*"} || return 1
  rc
}

# repoman commit with the message from the ChangeLog
rc() { 
  declare msg

  if [[ -n $* ]]; then
    msg="$*"
    echo "Using msg from command-line" >&2
  else
    msg=$(perl <ChangeLog -0777 -pe \
      's/^.*?\n  \d{2} \w{3} \d{4};.*?:\n//s || exit 1; # trim top
       s/\n(?:\*|  \d{2} \w{3} \d{4};).*//s;            # trim bottom
       s/^\s*//; s/\s*$//; s/^(?:  |\t)//gm;            # fix spacing
       #/^ /m || s/\s+/ /g;  # normalize spacing unless formatted
      ')
    if [[ $? != 0 || -z $msg ]]; then
      echo "couldn't parse message from ChangeLog" >&2
      return 1
    fi
    echo "Parsed msg from ChangeLog" >&2
  fi

  echo "----------" >&2
  echo "$msg" >&2
  echo "----------" >&2

  repoman commit -m "$msg" || return 1

  if [[ -x /usr/bin/eviewcvs ]]; then
    local f entry=$(perl -00ne '/^  \d/ and print, last' ChangeLog)
    entry=${entry%%:*}
    entry=${entry##*>}
    entry=${entry//,/ }
    for f in $entry; do
      [[ $f == -* ]] && continue
      f=${f#+}
      echo "$f"
    done | xargs -n1 eviewcvs
  fi
}

Regards,
Aron

--
Aron Griffis
Gentoo Linux Developer


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]