On Tue, Jun 10, 2003 at 11:35:30PM +1000, Daniel Stone wrote:
> On Tue, Jun 10, 2003 at 10:11:17PM +0900, ISHIKAWA Mutsumi wrote:
> > I believe changelog is a changelog, not a bug closer ;)
>
> Yeah. Branden and I discussed it a while back, and our conclusion was
> that we should only use the changelog for major events/news/bug-closing,
> not everything. The current xfree86 changelogs are massive, and we have
> our revision control system to fully log everything. Plus, crediting
> people right is a pain - what if two people work on something? Should
> Branden be credited? How much contribution gets a credit? That sort of
> thing. :)
I think you are misremembering a little bit, or misapplying our
agreement to the instant case.
Here's my proposal for commit and changelog handling for the X Strike
Force. These points are not very well organized because I'm writing
this mail in a hurry. If there is agreement on these points I'll add
them to the top-level README.
* When committing new code (that is, not merging), do so in discrete
change sets. A change set is a collection of edits that have the same
purpose. For example, "stepped optimiziation level down to -O from
-O2 for the entire build" and "fix typos in Xsession.5 manage" are
distinct changes and should be committed separately. A change set can
affect multiple files, and can include operations such as adding,
removing, or renaming files. The import thing is that all the changes
in the commit are directed towards achieving the same goal.
* Sometimes we are simply doing a review of existing code or
documentation, not reacting to a problem or bug report. In such cases
sometimes the best thing to do simply commit all changes to a file in
one change set. For example, "overhaul Xsession.5 manpage". This is
a matter of discretion. When deciding what should go into your commit
(a.k.a. change set), ask yourself how much extra work will be made if
anything in your commit has to be reverted in the future. It is
unlikely that a typo fix will be reverted, but if your typo fixes are
mixed in with the addition of a new chunk of code that may be reverted
later, then that reversion will mean the typo fixes have to be
re-committed. Worse, the person reverting your change may forget to
re-commit the typo fixes!
* When committing a merge operation, identify in the commit log which
range of revisions is being merged onto the branch (or the trunk, if
you're merging onto the trunk). For example:
merging revisions 156--170 from trunk onto branches/4.3.0/sid
* When doing a commit that should be logged in the debian/changelog
file, edit the debian/changelog file before doing the commit and
commit the change to it along with the rest of your change set.
* Here's a new one that I myself didn't realize was important until this
morning: always include the name of each file being changed in your
commit log. This seems redundant until you realize that "svn log"
operations can be run on directories. For example, I did an "svn log
branches/4.3.0/sid" this morning and saw this:
------------------------------------------------------------------------
rev 172: ishikawa | 2003-06-10 06:44:45 -0500 (Tue, 10 Jun 2003) | 3 lines
always disable FontLibSharedFreeType
------------------------------------------------------------------------
rev 170: branden | 2003-06-09 15:29:19 -0500 (Mon, 09 Jun 2003) | 2 lines
install the unstripped library in /usr/X11R6/lib/debug, not /usr/X11R6/lib
------------------------------------------------------------------------
rev 169: branden | 2003-06-09 15:27:36 -0500 (Mon, 09 Jun 2003) | 2 lines
import 4.2.1-8 changelog and clean up 4.3.0 entries
------------------------------------------------------------------------
rev 168: ishikawa | 2003-06-09 14:08:23 -0500 (Mon, 09 Jun 2003) | 3 lines
Imake waring fix
------------------------------------------------------------------------
rev 166: ishikawa | 2003-06-09 11:02:36 -0500 (Mon, 09 Jun 2003) | 3 lines
resync with 4.2.1-8
------------------------------------------------------------------------
rev 138: branden | 2003-06-04 08:06:54 -0500 (Wed, 04 Jun 2003) | 2 lines
usr/X11R6/lib/modules/libint10.a is back for IA-64
------------------------------------------------------------------------
rev 129: daniel | 2003-06-03 07:49:48 -0500 (Tue, 03 Jun 2003) | 2 lines
i830 fix from Egbert Eich - apparently it's completely unusable without this.
That's not as useful as it could be. Look at how the Subversion guys
do commit messages:
Regression test for issue #1353: handle twice-deleted file. Also,
fix some bugs discovered in the process of making the new test.
This twice-deleted file issue is quite similar to the one described in
issue #1302; but there are enough variables between the two that an
isolated regression test is a good idea.
* tools/cvs2svn/cvs2svn.py
(make_path): Fix bug in handling of top-level files.
(Dump.start_revision): Increment revision at the end of the
function, not the start, to avoid dumpfiles starting with
revision 2 instead of 1.
(usage): Document --no-prune option.
(main): Allow --no-prune option in getopt.
* tools/cvs2svn/run-tests.py
(ensure_conversion): Take no_prune boolean, defaulting to None.
Pass --no-prune to cvs2svn if no_prune is true.
(double_delete): New test.
(test_list): Run it.
* tools/cvs2svn/test-data/double-delete-cvsrepos/: New name for
directory 'double-removal' -- works with the conventions in
run-tests.py, and is more euphonious besides.
Much better, eh?
* As far as what should be logged in debian/changelog goes:
+ Anything that affects binary compatibility.
+ Anything that fixes an outstanding Debian bug report.
+ Anything that discernibly changes the behavior of code from a
black-box perspective.
+ Anything that changes an interface, be it a C function, a
command-line program, or whatever.
+ Substantial additions or removals of documentation or code comments.
What shouldn't be logged in debian/changelog:
+ Anything cosmetic. Whitespace cleanup, fixes to indentation (except
in Python code, heh), typo fixes in documentation or comments.
When writing a changelog entry for a new upstream release, we should
not recapitulate the upstream changelog or release notes except where
to do so helps us close an outstanding bug report. For example:
* new upstream release
+ adds support for ATI Radeon 9500 chipsets (Closes: #123456)
What do you guys think?
The goal is NOT to make the package changelogs less massive. The goal
is to make them more useful. My package changelogs have been doing
double-duty for years because I didn't have them under revision control.
Now they simply need to do what a changelog should do -- log changes.
Anyway, as to the point at issue, I don't think there is anything wrote
with ISHIKAWA-san's update to debian/changelog. It was a fairly
important change to the build process.
--
G. Branden Robinson | Good judgement comes from
Debian GNU/Linux | experience; experience comes from
branden@debian.org | bad judgement.
http://people.debian.org/~branden/ | -- Fred Brooks
Attachment:
pgpUSbl8QGnZv.pgp
Description: PGP signature