[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

RE: Version change rationale.

From: Owen Thomas <othomas_at_wcg.net.au>
Date: 2007-01-11 04:25:26 CET

Thanks Jared (and Mark) for your comments. They are very helpful in
allowing me to argue the merits for and against an implementation of
this change rationale system.

> I think what Jeff, Eric, and Mark were getting at, is that you could
> re-conceptualize the svn:log property data, and transform it into your
> "Change Rationale" format.

Hmmm... I'm learning about svn:log as I write this.

> Think of svn:log as a text file that always gets added with each
> revision.

That isn't a good image in terms of what details I want to record in a
change rationale document. My reason for this statement is that all
changes consequent to a revision are recorded in one file. While svn:log
is very good for recording a revision's summary information about a
whole change (and I will probably be using it as such) I fear it might
become bloated and unmanageable recording rationale to changes in
individual files affected by the revision. This is especially true for
revisions that affected many (50 or more, say) modules.

> It can even be changed later, after commit.

Now that's a definite point against the use of svn:log for recording
change rationale. Rationale is history. What has happened happened, and
nothing can be done to un-happen what has happened.

> You can format this text data any way you want, CSV, ODF, XML,
> YAML, INF, CONF, etc. Or make up your own format.

As said in an earlier post, if I can have this, I will.

> Either way you implement this "Change Rationale" system, you're
> going to need to wrap your "svn commit" actions with some custom
> script to initiate the "rationale input step".

I intend to attach a script to the pre-commit hook. Amongst many QA
checks that it will make are that the document has been changed, and the
changes are only within certain bounds.

If I use an OpenOffice text table for instance, I should be able to make
sure that one row to this table has been added, and that that row
contains three columns, the two that contain the revision number and
commit date are empty, and that at least there is some text in the
third.

> This wrapper script will probably open your editor of choice, and
> always start on some basic template.

I can understand where you're coming from here as I had considered it
briefly myself. Although I think having an editor open at the time the
changes are committed sounds like a nice way to cater for entering
rationale, it forces the developer to enter the rationale quickly. This
aint so good. The developer should consider that the justification for a
change is at least as important as the change itself.

> If you get sufficiently fancy, the template or form fields can be
> based on a list of files returned from "svn status", and maybe even
> list changed line numbers returned for each file by a diff,
> presenting the diff lines for convenience of reference (but not
> including them in the file directly).

Gee, I salivate at the chance of getting this fancy. I might supply the
list of files included in the change in the svn:log entry. The rest, I
could put in each change rationale document. I'd love the document to
have diff output that was as verbose as possible! Hmmm... maybe not that
verbose.

> Likewise, you may want to wrap any "svn log" command to return some
> method of opening any svn:log or rationale-file entry in the list
> in your desired editor/viewer.

Hmmm... not too sure what you are driving at here. I'd love an
explanation.

In my system, the change rationale documents are being versioned with
the project source, so are available to be checked out along with the
modules that are subject to possible change.

> Once those tools are done, it shouldn't much matter whether that
> rationale data is stored in svn:log or some other file or database.
> svn:log is already there, so you might as well use it.

Well, I have two beefs about using svn:log: I believe it isn't subject
to version control, and I don't like the prospect of recording changes
to all modules in one file, especially when a revision involves changing
many code base files.

Thank you for helping me decide what I should do. I'd really like to
know if my knowledge of SVN appears wrong in anything I have so far
said. If you're beginning to like the idea, I'd also love to hear from
you too - that'll give me some impetus to go ahead with my plans.

Thanks,

  Owen.

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Thu Jan 11 04:25:55 2007

This is an archived mail posted to the Subversion Users mailing list.