Re: [gentoo-dev] ChangeLog generation - pros and cons (council discussion request)

[Nirbheek Chauhan]

On Thu, Jun 2, 2011 at 2:43 PM, Fabian Groffen <grobian@g.o> wrote:
> I start from the assumption that generation of ChangeLogs is NOT limited
> to any VCS.

This assumption is incorrect, but I guess it's a close enough
approximation for the current discussion.

> Simple pros I see mentioned:
> - no more need for echangelog + repoman commit (identical message)

This can be done without autogeneration as well. We can make repoman
commit run echangelog before cvs commit. The main advantage is that
there's no duplication of information, which would result in a less
bloated repository.

> - no discussion on what to include or not (everything is in there)

In git, we can make git log skip commit messages while generating the
ChangeLog, so this is incorrect. See section "Commit Limiting" in git
log --help.

> Simple cons I see mentioned:
> - useless information on removals of ebuilds/files
> - useless information on whitespace changes

None of these are valid with Commit Limiting and a tag such as
'[trivial]' in the commit message subject.

> - inability to edit ChangeLog entries (typos, bug refs, etc.)
>

See "git notes --help". It allows you to append notes to commit
messages without editing them.

> 1) it appears echangelog messages more than just a couple of times
>   differ from the repoman commit messages; sometimes useful information
>   is lost when just using the VCS logs
> 2) typo fixing on VCS-generated logs is sometimes necessary, but
>   probably impossible
> 3) dates and new ebuilds generated from VCS are always correct,
>   ChangeLog editting/echangelog -> commit delays can cause
>   inconsitencies
> 4) package moves might lose all history for essentially the same files
> 5) entries for all commits show up, including those that weren't
>   originally tracked in ChangeLog for some reason
>

All these problems are fixed if we don't re-generate the *existing*
ChangeLogs. We should simply archive the existing ChangeLog, and
append to it after the move to git.

Since the beginning, we've been working with the assumption that
ChangeLogs can be edited. This has caused a *lot* of quirks to appear
as you've demonstrated.

Infact, if you do the same experiment on the openrc ChangeLog, you'll
see that it's too much work to regenerate the current ChangeLog
because a few commits managed to change the encoding of names in the
file, and a reverse-patch had to be applied to fix it. A number of
developers have made this mistake, and it shows up across the tree.

> If a move to VCS-generated ChangeLogs is to be made, it appears the
> council has to decide that the following is desirable:
> - a commit message is supposed to be always right/correct
> - since the commit message is right, either
>  - repoman commit runs echangelog, or
>  - ChangeLogs are generated on current CVS as well
> - any typos and incorrect refs, bugs, messages, etc. are accepted as
>  drawback of the system that does not compare to its advantages

We can append to existing commit messages using git-notes. Typos are
hard to fix, but using git-notes to include sed commands, we can hack
up a solution if there's a *pressing* need for it.

As a result, commit messages are supposed to be double-checked with
git log -p before pushing; but if you make a mistake, that can be
fixed as well.

> - it is accepted that all current information in the ChangeLogs gets
>  lost in favour of the VCS commit messages

This is not an issue if we archive and re-use the current ChangeLogs.

> - there is no point in discussing what should be in or out of a
>  ChangeLog, since by definition, "everything" is in (and tools should
>  effectuate so ASAP)
>

This issue will come up again if we implement commit-message limiting
using a [trivial] tag.

> If the council deems a separate ChangeLog file useful, they decide that:
> - ChangeLog messages can (and sometimes should) be different from commit
>  messages, as they are intended as information for users

In git, there's no harm with making commit messages verbose, so we
should give as much information as possible. However, if some
developers *really* don't want some lines to show up in the ChangeLog,
they can prepend it with a '#omit' (or similar), and the
ChangeLog-generating script will skip those lines.

> - editting ChangeLog messages is necessary to emit the most correct
>  information to our users at all times

Once again, git-notes.

> - a clear policy is necessary on what is going in the ChangeLog and what
>  not (like the current "common sense" discussions going on and the
>  updated devmanual)

However, with git the issue is simplified because then developers will
stop relying on ChangeLogs for information, and ChangeLogs will be
used entirely to convey information to users.

> - basically nothing changes, and the whole idea of generating ChangeLogs
>  from VCS is no longer a point of discussion
>

I'm not sure I understand this.

-- 
~Nirbheek Chauhan

Gentoo GNOME+Mozilla Team