Re: GNU ChangeLogs, commit logs and commits
On Fri, 13 Feb 2009, Guillem Jover wrote:
> So, I think if we have to switch, we should drop completely the GNU
> style ChangeLog format and use normal git style commit logs.
So we would drop ChangeLog but also all the others, right?
scripts/po/ChangeLog
po/ChangeLog
dselect/po/ChangeLog
man/po/ChangeLog
> ,---
> possible-subsystem: short summary
>
> Narrative explanation of the change if needed.
> `---
Fine for me.
> Rename the current ChangeLog files to ChangeLog[.-]old or whatever and
> then simply generate the whole new ChangeLog at «make dist» time, from
> the point were we switched, with something like:
So we would drop ChangeLog but also all the others, right?
scripts/po/ChangeLog
po/ChangeLog
dselect/po/ChangeLog
man/po/ChangeLog
Otherwise, the information is duplicated. And my complicated system was
only meant to split the changelog info in the various changelog files.
> ,---
> .PHONY: ChangeLog
> ChangeLog:
> git log -C --stat 1.15.0.. >$@
> `---
Fine for me.
> I'd leave the discussion about debian/changelog conflicts for later.
> Let's do a step at a time.
IMO those are not a problem. They are fairly short and should in general
not be included in any private branch. The required entry should be added
when the branch is merged in master. If one merges his own branch, he can
just git commit --amend to add the description (before or after the
merge). If one merges a branch done by someone else, he can just add a
separate commit adding the debian/changelog entry.
> Something I'd like us to adhere to, though, is:
>
> * Short summary should be distinguishable:
> - Stuff like “Updates” is not useful.
+1 (and most translation updates should have only that line with a
somewhat standardized format)
> * Informative and clear commit logs:
> - No rants, etc (those are not blog posts :).
Haha, Christian, that's for you. :) Fine with me anyway, I like reading
the rationale in the long description.
> * Correct attribution information:
> - Use --author when committing on behalf of someone else.
> - Probably use more Foo-by: pseudo-fields.
Yes, we should document those pseudo-field on
http://wiki.debian.org/Teams/Dpkg/GitUsage
Right now we have almost never used any except "Reported-by:" but we have
plenty of "Based on a patch by".
$ git log | grep "Based on a patch by" |wc -l
23
> * Small logical unit commits (if it cannot be described fully in the
> short summary, then there's probably too many changes):
> - Others do not get put off by monster commits, or trying to mentally
> untangle the unrelated changes in their minds.
> - Makes it easier to verify for correctness, avoid regressions, etc.
> - Makes it easier to revert or cherry-pick if needed.
Fine with me. It's not always doable or convenient. For example, I'm
rewriting update-alternatives right now and can't commit that in many
small steps that make sense (either update-alternatives would be broken in the
intermediary steps or it would require heavy usage of git add -p to
untangle the new code from the parallel adjustement of the current code).
But in general I think that we already follow that rule. Or did you note
some commits (from me) that were too big and/or mixing different changes ?
Cheers,
--
Raphaël Hertzog
Le best-seller français mis à jour pour Debian Etch :
http://www.ouaza.com/livre/admin-debian/
Reply to: