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
