Re: ChangeLogs

[John W. Eaton]

On 18-Jan-2009, Thorsten Meyer wrote:

| I also like this solution. Yet I am still a little confused about what it 
means in detail. Let me
| try a little recap. The proposal seems to be this:
|  - We no longer write ChangeLog entries
|  - Instead write commit messages like in John's example:
| 
|     one line summary
| 
|     * file1.cc (function): What changed.
|     (other_function): Other change.
|     * file2.cc (function): Another change.
| 
|  - The old ChangeLog files are renamed to ChangeLog.number
|  - ChangeLog files are generated using
|      hg log --style=changelog
|    with releases of octave.
| 
| I have a few questions:
|  - how to we credit contributions of people who do not push to savannah 
themselves in the future?

When you create the changeset, you can use the 

  --user "user name <address@hidden>"

option to commit, qnew, or qrefresh.  That way the specified user name
shows up in the commit log instead of your ID.  I also recomment using
the --currentdate option to qnew or qrefresh so the timestamp on the
patch is updated each time you refresh a patch in the MQ.  I have this
as a default in my .hgrc file:

  [defaults]
  qnew = --currentdate --currentuser
  qrefresh = --currentdate

|    I think we should add the name of the contributor to the commit message 
(unless
|    contributor=committing person).

I think all that needs to be done is for you to use the --user option
when commiting a change.

|  - Should we also add the creation date of the patch?

I don't see that this date is important.

|  - Will there be some correspondence between the names of the NEWS files and 
the names of the
| corresponding (autogenerated) ChangeLog files?

The NEWS file should be created by hand.  It should list user-visible
changes.  Ideally, each changeset should include

  a patch for the sources that meets the coding conventions

  a commit log entry in the format above

  a NEWS file entry if there is a user-visible change

  an update to the user manual if there is a user-visible change

I know that I've been quite negligent when it comes to updating the
NEWS file and user manual, and currently we don't require contributors
to have all these things done before accepting a patch (mostly for
fear of making the barrier to contributing too high).  Plus, until now
we've not really had much of a guide for contributors.  So I've tended
to fix up formatting issues and write ChangeLog entries myself.  But
as the number of contributors increases, we may want to be more strict
in the requirements, so that contributors are doing some of this work
instead of us.  But we'll have to make a case for why these rules
matter, as my sense is that many contributors don't see the point.
But I certainly think it is important for the sources to have a
consistent appearance as it makes them easier to read.

|  - Or will there be only one big ChangeLog file containing everything changed 
from now on?

Yes, there will only be one ChangeLog file at the top level in the tar
file distributions.

jwe