Subject: rev 27 - trunk

From: [email-masked]
Date: Mon, 26 Aug 2002 06:56:46 -0500

Author: loredana
Date: Mon, 26 Aug 2002 06:56:43 -0500
New Revision: 27

Modified:
   trunk/Makefile.in
Log:
Log:

* Top level Makefile.in
  Add www/ to the dist-dir
  
Here is the original bug report:

  From: Loredana Lo Conte <[email-masked]>
  Subject: Ale rev 26
  To: [email-masked]
  Date: Fri, 23 Aug 2002 22:04:49 +0100 (BST)

  [...]

  1) www/index.html is missing in ale-0.1.186.tar.gz

    % gunzip -c ale-0.1.186.tar.gz | tar -xvf -
    % cd ale-0.1.186
    % ./configure
  [...]
  config.status: creating www/index.html
  config.status: error: cannot find input file: www/index.html.in

  I copied index.html.in from the working copy and the rest of it was ok.

* Top level Makefile.in
  remove MINOR-BUGS from dist-dir, not part of the distribution anymore

Modified: trunk/Makefile.in
==============================================================================
--- trunk/Makefile.in	(original)
+++ trunk/Makefile.in	Mon Aug 26 06:56:45 2002
@@ -154,8 +154,11 @@
 dist-dir:
 	mkdir ${DISTDIR}
 	ln configure.in configure config.guess Makefile.in ale.in ${DISTDIR}
-	ln BUGS ChangeLog.CVS MINOR-BUGS README WISHLIST ${DISTDIR}
+	ln BUGS ChangeLog.CVS README WISHLIST ${DISTDIR}
 
 	mkdir ${DISTDIR}/demo-data
 	ln demo-data/demo.gb ${DISTDIR}/demo-data/demo.gb
 	ln demo-data/demo.phylo ${DISTDIR}/demo-data/demo.phylo
+
+	mkdir ${DISTDIR}/www
+	ln www/index.html.in ${DISTDIR}/www/index.html.in

---

From: Karl Fogel <[email-masked]>
Date: 26 Aug 2002 07:20:42 -0500

> Any comment about my first commit? (Aside from Log: Log:)
> Bad behaviour must be corrected before it becomes bad habit :)

Only some comments about the log message (see below).  The changes
themselves look great!

Brava for your first commit :-).

>   remove MINOR-BUGS from dist-dir, not part of the distribution anymore

You don't have to write "* Top level Makefile.in".  By default, paths
are relative to trunk/.  So you can just write "* Makefile.in".

IMHO, including the original bug report (the "[...]" above) for a
simple change like this isn't really necessary.  The change itself
quite explains what's going on.  I probably didn't need to include the
original bug reports in revisions 19, or even 18 -- I mainly did it
then so you'd know which bug I had fixed when you saw the commit.

Also, for Makefiles we usually name the affected make rule, in this
case `dist-dir'.  This isn't a hard and fast policy, though: compare
the log messages for revisions 11 and 7, for example.

Finally, your should generally mention a file just once, and say
everything about the file there.  For example, here are two ways to
write the log message:

   * Makefile.in
     (dist-dir): Add www/ to the dist, and don't include MINOR-BUGS.

or, equally good in my opinion:

   * Makefile.in
     (dist-dir): Adjust for recent changes.

With the simpler log message, the reader simply knows to view the diff
to get more detail.  The log message is essentially saying "This is a
self-documenting change, see the diff for more."

Jim Blandy once made some guidelines for writing log messages; we
adopted them (slightly modified) for the Subversion project.  Here
they are:

Writing log messages
====================

Certain guidelines should be adhered to when writing log messages:

Make a log message for every change.  The value of the log becomes
much less if developers cannot rely on its completeness.  Even if
you've only changed comments, write a log that says "Doc fix." or
something.

Use full sentences, not sentence fragments.  Fragments are more often
ambiguous, and it takes only a few more seconds to write out what you
mean.  Fragments like "Doc fix", "New file", or "New function" are
acceptable because they are standard idioms, and all further details
should appear in the source code.

The log message should name every affected function, variable, macro,
makefile target, grammar rule, etc, including the names of symbols
that are being removed in this commit.  This helps people searching
through the logs later.  Don't hide names in wildcards, because the
globbed portion may be what someone searches for later.  For example,
this is bad:

   * twirl.c
     (twirling_baton_*): Removed these obsolete structures.
     (handle_parser_warning): Pass data directly to callees, instead
     of storing in twirling_baton_*.

   * twirl.h: Fix indentation.

Later on, when someone is trying to figure out what happened to
`twirling_baton_fast', they may not find it if they just search for
"_fast".  A better entry would be:

   * twirl.c 
     (twirling_baton_fast, twirling_baton_slow): Removed these
     obsolete structures. 
     (handle_parser_warning): Pass data directly to callees, instead
     of storing in twirling_baton_*. 

   * twirl.h: Fix indentation.

The wildcard is okay in the description for `handle_parser_warning',
but only because the two structures were mentioned by full name
elsewhere in the log entry.

Note how each file gets its own entry, and the changes within a file
are grouped by symbol, with the symbols are listed in parentheses
followed by a colon, followed by text describing the change.  Please
adhere to this format -- not only does consistency aid readability, it
also allows software to colorize log entries automatically.

If your change is related to a specific issue in the issue tracker,
then include a string like "issue #N" in the log message.  For
example, if a patch resolves issue 1729, then the log message might
be:

   Fix issue #1729:

   * get_editor.c
     (frobnicate_file): Check that file exists first.

For large changes or change groups, group the log entry into
paragraphs separated by blank lines.  Each paragraph should be a set
of changes that accomplishes a single goal, and each group should
start with a sentence or two summarizing the change.  Truly
independent changes should be made in separate commits, of course.

One should never need the log entries to understand the current code.
If you find yourself writing a significant explanation in the log, you
should consider carefully whether your text doesn't actually belong in
a comment, alongside the code it explains.  Here's an example of doing
it right:

   (consume_count): If `count' is unreasonable, return 0 and don't
   advance input pointer.

And then, in `consume_count' in `cplus-dem.c':

   while (isdigit ((unsigned char)**type))
     {
       count *= 10;
       count += **type - '0';
       /* A sanity check.  Otherwise a symbol like
         `_Utf390_1__1_9223372036854775807__9223372036854775'
         can cause this function to return a negative value.
         In this case we just consume until the end of the string.  */
      if (count > strlen (*type))
        {
          *type = save;
          return 0;
        }

This is why a new function, for example, needs only a log entry saying
"New Function" --- all the details should be in the source.

There are some common-sense exceptions to the need to name everything
that was changed:

   *  If you have made a change which requires trivial changes
      throughout the rest of the program (e.g., renaming a variable),
      you needn't name all the functions affected, you can just say
      "All callers changed".

   *  If you have rewritten a file completely, the reader understands
      that everything in it has changed, so your log entry may simply
      give the file name, and say "Rewritten".

   *  If your change was only to one file, or was the same change to
      multiple files, then there's no need to list their paths in the
      log message (because "svn log" can show the changed paths for
      that revision anyway).  Only when you need to describe how the
      change affected different areas in different ways is it
      necessary to organize the log message by paths and symbols, as
      in the examples above.

In general, there is a tension between making entries easy to find by
searching for identifiers, and wasting time or producing unreadable
entries by being exhaustive.  Use your best judgment --- and be
considerate of your fellow developers.  (Also, run "svn log" to see
how others have been writing their log entries.)