[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

proposed X Strike Force commit/changelog policy

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: pgp4smgOokZad.pgp
Description: PGP signature

Reply to: