Hello Matt.
>> 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.
> why would you commit that many separate changes in one group?
I've been a developer long enough not to make any bold assertions about
what I might want. I have accepted as a maxim that systems under the
most stringent quality controls will need changes that non-trivial at
some point in their life. If they don't manage to adapt to non-trivial
changes, they will be surpassed by systems that do. My job as a
developer is to maximise the longevity of a system so that it doesn't
have to be replaced. Including change rationale is a very effective way
of ensuring this.
<snip/>
>>> 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.
> only when properly set up - its not on by default
So you can turn on a 'can't touch this' switch? Still, I like the idea
of versioning the rationale. SVN and the general concept of code
versioning were conceived as a way of up-happening mistakes. I'd like to
capitalise on this for the rationale as well as the code.
<snip/>
>> 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.
> basically - if you are going to store this much meta-information -
make
> sure you can read it later
I see. My change rationale documents are checked out like any document
under version control. Therefore they are available to be edited the
same as any other document.
Owen.
________________________________
From: Matt Sickler [mailto:crazyfordynamite@gmail.com]
Sent: Thursday, January 11, 2007 2:36 PM
To: Owen Thomas
Cc: users@subversion.tigris.org
Subject: Re: Version change rationale.
On 1/10/07, Owen Thomas <othomas@wcg.net.au> wrote:
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.
why would you commit that many separate changes in one group?
> 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.
only when properly set up - its not on by default
> 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.
basically - if you are going to store this much meta-information - make
sure you can read it later
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.
it isnt versioned, but each revision has its own svn:log property
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 05:20:22 2007