[documentation] -- versus - in "new release" system

[Derek Wright]

On Dec 6, 2006, at 2:58 PM, Andre Molnar wrote:

> Sad to say it is hopelessly un-clear... You are correct in saying that
> much of this information is technically 'different' - but not  
> different
> enough - or rather - far too similar - and the result is absolute  
> confusion.

there's 2 things:

1) version numbers.
http://drupal.org/handbook/version-info

2) the CVS tags and branches that they correspond with.
http://drupal.org/handbook/cvs/branches-and-tags

people like version numbers with '.' in them, like "4.7.4".  CVS  
doesn't allow '.' in a tag, so we have to use '-' instead.  *shrug*.

> I was reading the CVS documentation today because I wanted to roll  
> out a
> release of a new contrib module.  Quite frankly the documentation  
> is so
> confusing that I was afraid to try and commit something for fear I  
> might
> break the entire freaking conrtib repo.

luckily, our CVS repository protects itself from people who don't  
know what they're doing.  so, the worst you could have done was break  
your own modules. ;) even that is pretty hard to do, thanks to all  
the defensive checks i've put in place.

> (I'll get over my fear eventually - once i digest the information
> again).  The worst part about this is that I don't have suggestions  
> for
> improvement, because I don't 'get it' and therefore couldn't  
> express the
> information in a way that others might 'get it.'

well, if all you say is "it's too much, it's too confusing, i don't  
get it", there's no hope anyone can make it any clearer.

if you offer concrete suggestions for improvement, great.
if not, at least be specific about what you're confused about.

not that it helps you, but it seems like dozens (if not over a  
hundred) project maintainers have read the docs and are getting along  
just fine, so i know they're not inherently impossible to read.  but,  
everyone's at a different level of comfort with release management,  
so different folks will read the same docs and come away with a very  
different grasp (or not grasp at all) of the info it was trying to  
convey.

> Can we just switch to SVN ;-)

absolutely *nothing* would change about any of the release system if  
we were using SVN instead of CVS.  if you honestly think "svn  
tag ..." is fundamentally different than "cvs tag ..." you're in for  
quite a disappointment if/when Drupal ever switches to SVN.

any additional complication from the new release system is inherent  
to using a real release procedure for our software.  the underlying  
revision control tool makes no difference at all (since all revision  
control systems provide the same basic functionality: commits, tags,  
branches, etc).

i'm not saying a) the docs are perfect or b) that you're an idiot.   
i'd love to see the docs improve, and if you're confused, i'm sure  
you're not the only one.  but, "i don't get it, we should just use  
SVN" is counter-productive feedback on 2 counts. ;)

thanks,
-derek