You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@subversion.apache.org by Martin Ankerl <ma...@gmail.com> on 2005/07/28 09:51:47 UTC
subversion guideline
Hi everyone,
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!
--
Martin Ankerl | http://martinus.geekisp.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: subversion guideline
Posted by Simon Ward <si...@mivok.net>.
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
Re: subversion guideline
Posted by Martin Ankerl <ma...@gmail.com>.
Thanks for the suggestions!
Here is an updated version of the guideline, feel free to modify it
however you like:
http://martinus.geekisp.com/files/subversion/SubversionGuideline.doc
http://martinus.geekisp.com/files/subversion/SubversionGuideline.ps
http://martinus.geekisp.com/files/subversion/SubversionGuideline.pdf
--
Martin Ankerl | http://martinus.geekisp.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Re: subversion guideline
Posted by William Nagel <bi...@stagelogic.com>.
Hi Martin,
Nice job. Very concise. Looks good. Lots of info. I do have a
couple of suggestions, though.
1) Commit, point #2: 'hindered' is misspelled as hintered
2) I'm not so sure about the prefixes. I can see their usefulness,
but I think they may encourage a tendency to use them as a crutch,
which may lead to less useful text describing what was done, which
leads me to
3) Your sample commit message doesn't seem to be very descriptive.
It tells what was done, but doesn't say why it was done, which is
often much more useful. It also doesn't seem to follow your own
advice. It appears that there are two (at least) conceptual changes
involved in the example commit message.
Overall though, it looks pretty good. There are a lot of legitimate
reasons for individual projects to do things differently than you
describe, but for general best practices they seem to be good advice.
-Bill
On Jul 28, 2005, at 4:51 AM, Martin Ankerl wrote:
> Hi everyone,
>
> 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!
>
> --
> Martin Ankerl | http://martinus.geekisp.com/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: users-help@subversion.tigris.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org