Hello.
I thank Jeff and Eric for both replies I have thus far received on this
subject. I apologise to them if I have misunderstood what they were
trying to say. I am still looking at their replies and I will post a
correction if I reach enlightenment.
There seems to be some disparity between what I want to do and what
people are telling me there is, or maybe I haven't yet divulged all so
that you can give a more informed comment. I am also quite new to SVN
and not all that much of an old-hand (although I have had reasonable
exposure to CVS and some contact with ClearCase) at versioning in
general. I have very much so, and for some years, seen the necessity of
version control. There is no need for further convincing in that
respect.
I have this idea:
I want to include a 'Change Rationale' document for each file under
version control. You may ask why, and my answer is simple: I want to
know why revision-such-and-such involved updating file so-and-so with
these-number-of changes. My solution: to have a separate file associated
with file so-and-so that gives the developer the opportunity to
succinctly yet comprehensively state why these-number-of changes were
necessary in terms of revision such-and-such.
I think this is a wonderful way of ensuring quality in a system, as it
gives future developers the opportunity of objectively looking at past
changes and asking themselves: are these-number-of changes still
relevant?
The SVN log seems fair enough for recording rationale against a
revision, but does not appear to be sufficient in terms of recording
rationale against changes in a particular file of the revision in
question.
This is a rough directory structure of the implementation I have been
thinking about. All of these directories are under version control.
Development/
CodeBase/
Project1/
Project2/
...
ChangeRationale/
Project1/
Project2/
...
Documentation/
Project1/
Project2/
...
The CodeBase directory is self explanatory. It is where all the project
sources are, in each project (Project1, Project2, ...) that is being
managed.
The documentation directory is also self explanatory. It contains
documentation in whatever form suits the each managed project.
The ChangeRationale directory is key to my idea. Each CodeBase directory
has a directory structure which is copied in the ChangeRationale
directory so that every file in the CodeBase directory contains an in
situ document in the ChangeRationale directory. Each change rationale
document would have a very specific structure that permitted updates
only in a very specific way so that a script associated with the SVN
pre-commit hook could be used to check that the file has indeed been
updated in this specific way before committing the changes.
I envisage this change rationale document would contain a table that had
columns for a revision number, commit date, and the justification
comment. It wouldn't be a text file because I would like the document to
contain links to other information (especially information in the
Documentation directory) if the developer thought this was important. I
am hoping that OpenOffice's .odf format will work here.
I am of the view that if the developer thought it important to scratch
their elbow at some point during the work, the developer should be
provided the opportunity to justify this decision. All of this
information is kept away from the code because, but for the revision
number which would be a token that was substituted at commit time, the
developer wouldn't feel as compelled as they might to record
justification in code comments.
Provided developers are as habitually attuned to fastidiously recording
justification to file changes as I might be (I literally shine with
retentiveness) a code base should be clean, lean, and joy to maintain
for decades thereafter.
What do you think? If you think it's a good idea, but you haven't seen
anyone do it, speak up - because that will encourage me to press on with
my solution.
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 01:43:37 2007