Martin Ankerl wrote:
> I have compiled a (very very short) subversion guideline from various
> sources. You can get it here:
>
> http://martinus.geekisp.com/files/subversion/SubversionGuideline.doc
> or in other formats:
> http://martinus.geekisp.com/files/subversion/SubversionGuideline.ps
> http://martinus.geekisp.com/files/subversion/SubversionGuideline.pdf
>
> Suggestions welcome!
Hi, nice handy little guide, fits on one page, something I have been
meaning to do for a project I'm working on.
A few points:
I realise it is only a guideline, but some of the styles are determined
by the project or organisational policies. I think it would be much
better to try and generalise some parts of it.
I also tried to impose a rigid style for one project I play repository
master for, and found it did not work very well. It is much easier to
say that log messages should just include a description of the change,
and for certain types of commits, you should mention other things
(revision number for a branch/tag/merge, bug# that the change addresses).
I don't think log messages need the suggested prefixes. I prefer a
description of a change to be one or two (English language) sentences
(which may well look similar to your example logs). I think logs should
be written for humans to read. If a tool is to be used to process a
changeset, it can use the verbose or XML outputs for log messages, and
diff output (and possibly others) to work out the relevant information.
For bug fixes, this may depend on the bug tracking system in use,
although it usually suffices to include "Fixes #1234" at the start or
end of the message.
For branching, tagging and merging: I would suggest that the log
includes the fact that it is a "branch", "tag", or "merge", where from,
where to, and the revision numbers, though not necessarily a rigid format.
An exception might be made for merges, which are so far manually tracked
in log comments. If you are using some tool to track your merges, you
might want to apply a more rigid format.
Tag naming, again, the suggestion is fine, although there may be
different uses of tags across projects. More specifically, I tend to
prefix tags for releases by "rel" or "release" so they are easier to
pick out (sometimes I take it further for "stable" and "devel"
releases). I think, at the very least, the tag name should describe its
purpose (in no more than a few words). It might be useful to include
the date tagname, for example to present a nice ordered view of the
tags, or for releases where the date is one of the major attributes used
to differentiate between them. For other purposes, the date may be
determined using 'svn info' or through a repository browser.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Thu Jul 28 13:02:29 2005