CVS Quickstart Addendum [#267327]

There's one important thing missing from http://drupal.org/handbook/cvs/quickstart that may be confusing newbies: The article lists the relevant commands to perform the desired actions, but it fails to point out the importance of the state of the user's directory, when he enters those commands.

Under "Before branching or tagging" I'd suggest adding

Before you enter the command to create a tag or branch, double-verify that the directory you're about to tag or branch from, really has a) the branch and b) the version checked out (and committed, if necessary) that you want to tag or branch from.

I'm sure my prose can be improved, but you get the idea.

To see why this needs to be emphasized, look here, where a new maintainer took over a module at revision 1.2.
He made two more D5 commits to MAIN, bringing him to 1.4, but then
he branched for DRUPAL-5 from 1.1 (!) to create 1.1.2.1, and right away
he branched again, for DRUPAL-6--1 from 1.1.2.1 (!) to create 1.1.2.1.2.1.

He intends to go to DRUPAL-6--2 shortly — I mentioned the problem to him in http://drupal.org/node/149368#comment-870338 and told him how to proceed. He specifically said that he had read the Quickstart Guide, and this was the result of how he understood it.

I hope he'll find his way back to MAIN...

The next section, "Branching for a specific Drupal core version" and especially the "managing branches" link go right into the technicalities, but the reader doesn't really understand what he'd be doing. I'd suggest adding something like the following to the introductory "Before branching or tagging" section:

Generally, you should always work from the end of a branch or MAIN. You should always develop your latest version in MAIN, including creating release tags like DRUPAL-5--1-8 in MAIN, and you should not branch off MAIN until MAIN changes its "personality."

For example, to get ready to work on your major version 2 (in MAIN), branch for DRUPAL-5 and tag subsequent version-1 releases like DRUPAL-5--1-9 in that new branch, and version-2 releases like DRUPAL-5--2-0 in MAIN.

And, before you start porting to Drupal 6, branch for DRUPAL-5--2 (or DRUPAL-5, if you're still on version 1), so that you can continue to support both versions independently. When you're ready for Drupal 7, branch for DRUPAL-6--1, etc.

Comments

Comment #1

rmiddle commented 6 June 2008 at 01:21

I had a hard time understanding CVS and I still don't. It would be nice if the guide included a section for checking out a project before changing, checking out a branch before committing, I understand what I am suppose to be doing but getting CVS to do that is easier said then done. It would be really great to have something like a howto with step by step how to check out head, a certain branch, once checked out how to commit. How to manage more then 1 version. etc. I would guess that it is more likely someone would get involved with Drupal to co-maintain or take over a project then starting something new. Yet the quick start guide only tell you how to start a new project. The other part of the CVS handbook tell you why you should do thing not how. If you are brand new to CVS it can be hard to get your head around. Sorry for Ranting like this.

Thanks
Robert