[Monotone-devel] the changelog editor branch is ready for review

[Derek Scherger]

Hi folks, I think the experimental changelog editor branch that I've been

working on recently is to the point where we can consider merging it to

mainline. (see the net.venge.monotone.experiment.changelog-editor branch)

The original motivation for this branch was to help deal with the problem of

saying "commit" and then realizing that you forgot to specify a --branch option

while editing your commit message.

This branch changes a few things:

1. Allows not only the ChangeLog message to be edited, but also the Date, Author

   and Branch values associated with the revision.

2. Unifies the format of revisions displayed by status, commit and log so that a

   revision looks the same before it's committed, while it's being committed and

   after it has been committed.

   

3. Requires that the long date/time format used by status, commit and log

   preserves a date passed through a formatting and parsing cycle. The status

   command checks that the current format meets this requirement and warns if it

   does not and commit refuses to operate for formats that don't meet this

   requirement.

4. Changes the edit_comment lua hook to take only one argument. Existing hooks

   that override the default will need to be changed to work properly. One

   somewhat nice side effect of the changes here is that the addition and

   removal of MTN: prefixes is no longer done in both the lua hook and the

   associated C++ code.

There are some relatively minor things that are open for discussion:

1. There used to be a "magic" line that the old commit editor would include if

   the text of the commit message came from the cached _MTN/log file. This line

   existed so that a commit could be aborted. If there was data in the _MTN/log

   file the magic line had to be removed before the commit would proceed. With

   the new editor changes outside of the "legal zones" described below will

   abort the commit so there is no real need for a "magic" line anymore.

2. The default date formats on mainline use "%x" which (using en_CA.UTF-8)

   produce 2 digit years. This does not meet the requirement in point 3 above

   for years before 1969 or after 2068 (with glibc 2.1 or later). While this

   isn't a huge problem it might be a good idea to consider using the "%F"

   format which produces 4 digit years.

3. Changing text in the commit editor outside of the Author, Date, Branch and

   ChangeLog values is prohibited and will abort a commit because it may prevent

   these values from being found and extracted. Perhaps the entire contents of

   the editor should be saved to something like _MTN/changelog to prevent losing

   a long, carefully worded commit message entirely if you accidentally touch

   something outside of these "legal zones".

There are also some rather bikeshed-esque things that can be considered:

1. Currently the various cert headers all have a single space following the ':'

   character which doesn't line up their values very nicely. I think I would

   prefer these to be aligned left or right but I'm curious to see what others

   think.

2. The wording of the preliminary text describing what to do in the commit

   editor can probably be improved. This is a minor detail that can easily be

   changed later.

3. The "Changes against parent" line preceding the list of changed files and

   directories might be better as a "Changes: " line with an optional parent

   revision id which isn't included for root commits.

Examples

$ mtn status

----------------------------------------------------------------------

Revision: 90be95aa13e418be817cb85f7ec754cdf7b2389e

Parent: 8e8e71399ff9035409671f93723223430c26edc3

Author: address@hidden

Date: Tue Apr 06 10:39:38 PM 2010 -0600

Branch: net.venge.monotone.experiment.changelog-editor

ChangeLog: 

Changes against parent 8e8e71399ff9035409671f93723223430c26edc3

  patched  monotone.texi

  patched  tests/commit_using__MTN_log/__driver__.lua

  patched  tests/commit_using__MTN_log/commit_log_modified_return.lua

  patched  unit-tests/dates.cc

If there is a partial commit message in _MTN/log status will include it in the

ChangeLog section above, otherwise this section is empty.

$ mtn commit

======================================================================

Ensure the values for Author, Date and Branch are correct, then enter

a description of this change following the ChangeLog line. Any other

modifications to the lines below or to the summary of changes will

cause the commit to fail.

----------------------------------------------------------------------

Revision: 90be95aa13e418be817cb85f7ec754cdf7b2389e

Parent: 8e8e71399ff9035409671f93723223430c26edc3

Author: address@hidden

Date: Tue Apr 06 10:40:00 PM 2010 -0600

Branch: net.venge.monotone.experiment.changelog-editor

ChangeLog: 

Changes against parent 8e8e71399ff9035409671f93723223430c26edc3

  patched  monotone.texi

  patched  tests/commit_using__MTN_log/__driver__.lua

  patched  tests/commit_using__MTN_log/commit_log_modified_return.lua

  patched  unit-tests/dates.cc

======================================================================

Everything *between* the lines of ==='s appears in your editor. The values on

the Author, Date and Branch lines may be changed and the message is to be

specified on or after the ChangeLog line. If any unexpected changes are made

outside of these lines the commit is aborted.

$ mtn log

----------------------------------------------------------------------

Revision: 8e8e71399ff9035409671f93723223430c26edc3

Parent: 9b1c2736e8776622f62a61c5a87de31e4ab6ab32

Parent: f3e6ecbd06ccd1c7556e544f1e458aa58103db6c

Author: address@hidden

Date: Sun Mar 14 11:25:34 PM 2010 -0600

Branch: net.venge.monotone.experiment.changelog-editor

ChangeLog: 

merge of '9b1c2736e8776622f62a61c5a87de31e4ab6ab32'

     and 'f3e6ecbd06ccd1c7556e544f1e458aa58103db6c'

Changes against parent 9b1c2736e8776622f62a61c5a87de31e4ab6ab32

  patched  cmd_ws_commit.cc

Changes against parent f3e6ecbd06ccd1c7556e544f1e458aa58103db6c

  patched  NEWS

  patched  UPGRADE

  patched  configure.ac

  patched  testlib.lua

  patched  unit_tester.cc

  patched  visualc/config.h

  patched  win32/monotone.iss

I still need to write up a NEWS entry, update monotone.texi and maybe fiddle

with the output formatting a bit but otherwise I think this is done.

Cheers,

Derek