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

[Fabian Groffen]

I'm summarising this thread [0] for the upcoming council meeting.


Automatic ChangeLog generation

Some people have expressed disagreement with committing ChangeLog
updates for some changes.  Discussion on that lead to an updated policy
to document nearly all changes.  Some people still really disagree with
that and go as far to commit dummy placeholders just to make sure they
don't do what they deem is useless for everybody.

ChangeLog generation is often suggested as a solution to this by those
people who do not like to document their changes in the ChangeLog file.

Auto generation of ChangeLogs, implies changes, and also influences how
current ChangeLog information is to be handled.
What if auto-generation is done, what does it take?

- what messages to include (all?), what not to include (ignore some?)
-- ignore some messages, git: Commit Limiting ([trivial]) [1][3]
--- policy? what to ignore, what not? what does the current policy mean
    if commits can be made to be ignored?
-- only include messages for a time range, or relevant messages for
   current files (ebuilds) in the directory (package) [3]

= balance between hard policy effectuated by the generation and fuzzy
  control via keywords that is subject to the interpretation of the
  committer
= opening for new opportunities to safe space for and present more
  relevant information to our users

- inability to edit changelog entries (make corrections)
-- git: git notes --help -> append notes to commit msgs [1]
-- not a real issue [3]

= balance between either allowing it through complex scripting, or just
  ignoring the ability at all since it is rarely used and not done by
  others either ([3])

- history, ChangeLogs are often more useful than the CVS logs
-- retain existing ChangeLog and append? [1]
--- use setup with separate git repo for ChangeLogs [2]
--- auto-generate if non-existent (per maintainer pref) [3]
-- just forget it, it's old [3]

= balance between either retaining the original information, or
  forgetting about it completely since it is likely outdated information
  anyway -- note: this is only about differences in CVS log and
  ChangeLog
= balance between generating all ChangeLogs, or just those whose
  maintainer likes it


Generating ChangeLog opens opportunities (only commit, limit contents,
consistency), and can ease the life of developers.  However, the
currently existing ChangeLog files might differ from a generated one
from VCS logs significantly, if this is considered important, a strategy
for retaining the old messages has to be deployed (keep ChangeLog file,
store ChangeLog in separate repo, selectively retain ChangeLog files per
package).

If a ChangeLog is generated, are all commits to show up in them, or can
certain messages be ignored?  The latter requires specification of how,
but also when.  Updating a ChangeLog file is close to such situation
without policies.  Since commit messages cannot be changed, are methods
necessary to add notices to messages when they appear wrong/incorrect?

Should ChangeLogs be generated?
If yes
- should all commit message be included
- should commit messages be appended to/updated?
- should existing information in ChangeLog files be retained?


[0] http://archives.gentoo.org/gentoo-dev/msg_2ff02d6910d797045af3659fb21c712f.xml
[1] http://archives.gentoo.org/gentoo-dev/msg_934d783d619540a2e97725da7e767253.xml
[2] (not on archives.g.o and gmane) http://www.gossamer-threads.com/lists/gentoo/dev/231903?do=post_view_threaded 
[3] http://archives.gentoo.org/gentoo-dev/msg_3156112af9944a6c8736159247275ccb.xml



On 02-06-2011 11:13:38 +0200, Fabian Groffen wrote:
> Following up on the recent discussions about ChangeLogs, and what should
> be in there, versus what not, this email tries to describe the pros and
> cons of the frequently mentioned generation of ChangeLogs from the VCS
> we use.
>
> I would like the council to discuss the generation of ChangeLogs from
> the VCS in the next meeting for which this message is in time.  I prefer
> the council to decide upon whether or not generation of ChangeLogs is
> desirable for Gentoo or not.  In this email, I will try to describe the
> pros and cons, but I invite anyone else to contribute/discuss ideas.


-- 
Fabian Groffen
Gentoo on a different level