Author: branden
Date: 2003-06-18 11:48:45 -0500 (Wed, 18 Jun 2003)
New Revision: 210
Added:
HACKING
Log:
add HACKING file including proposed policies from earlier this month
Added: HACKING
==============================================================================
--- HACKING 2003-06-18 14:38:15 UTC (rev 209)
+++ HACKING 2003-06-18 16:48:45 UTC (rev 210)
@@ -0,0 +1,207 @@
+ Debian X Strike Force Hackers' Guide
+ ====================================
+
+Authors and contributors
+------------------------
+
+Branden Robinson
+Joey Hess
+Colin Watson
+ISHIKAWA Mutsumi
+
+Recommended best practices for handling commits and changelog entries
+---------------------------------------------------------------------
+
+* 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 optimization 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.
+
+ Q: As a point of interest, do you ever find yourself working on more than one
+ thing at a time in the same checkout, and how do you juggle the
+ debian/changelog changes then?
+
+ A1: When I find myself "forking" into two different change sets, I save the
file
+ I'm editing with a ".new" extension and then undo the changes that aren't
+ relevant to one of the change sets.
+
+ I then finish change set #1, document it in debian/changelog if
+ necessary, and commit.
+
+ I then mv the .new file on top of the original. It should now just have
+ a diff for change set #2. If need be, I edit it to continue working on
+ that change. When I'm done with that change set, I document it in
+ debian/changelog if necessary, and commit.
+
+ That's just my approach. I don't know if others would find it
+ palatable.
+
+ A2: I tend to changelog everything I do as I do it, then when I'm about to
+ commit I copy the working changelog aside and trim debian/changelog down
so
+ that the diff shows only one change set. After I commit, I move the
working
+ changelog back.
+
+* Sometimes we are simply doing a review of existing code or documentation, not
+ reacting to a problem or bug report, or implementing a new feature. 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 practice that Branden didn't realize was important until recently:
+ 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, Branden did an "svn log branches/4.3.0/sid" one
+ 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?
+
+ Q: Of course subversion knows what files that change touched. This sounds
more
+ like a deficiency of svn log; it should be able to list the files.
+
+ A1: Yes, and I'm tempted to agree about the output of svn log when run on a
+ directory, but I still think documenting the specific changes done to
each
+ file is a good idea.
+
+ A2: It can; use the -v option. I do tend to err towards verbose log messages
+ anyway, though.
+
+* 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)
+
+* There is also the issue of changelog format. In the past, entries in
+ debian/changelog were file-oriented; for example:
+
+ * debian/control:
+ - Change all references to libstdc++5-dev to be
+ libstdc++5-dev | libstdc++-dev, allowing libstdc++5-3.3-dev to satiffy
+ the dependency, and thus allowing gcc3.2 to be removed.
+ (Closes: #194136)
+ - New xlibmesa-drm-src package. (Closes: #139817)
+
+ Now, however, our work is change set-oriented, so it is preferable to
+ write each entry in debian/changelog to reflect that. For example:
+
+ * Use external Xft, Xrender and Xcursor libraries [ISHIKAWA Mutsumi]
+ - patch #058, #059, #060: new;
+ - patch #909: remove (reimplemented as above patches);
+ - xlibs{,-dbg,-dev}.*, shlibs*: drop Xrender and Xcursor related entries
+ - debian/control: add Build-Depends: libxrender-dev, libxcursor-dev
+
+ Each entry contains:
+ - short title of change set
+ - brief summary of changes made to each affected file
+ - bug-closing cross-reference (if needed)
+ - pointer(s) to further information (if needed)
+
+ Branden finds it useful to write the debian/changelog entry such that he can
+ use it (perhaps with elaboration) for the commit message as well.
+
+* Our overall goal with respect to the changelog entries is NOT to make them
+ less massive than they used to be. The goal is to make them more useful.
+ Branden's package changelogs have been doing double-duty for years because he
+ didn't have the package under revision control. Now they simply need to do
+ what a changelog should do -- log changes.
+
+$Id$
+
+vim:set ai et tw=80:
