Proposal for changing CVS branch conventions: contrib must always include "--N" in branch names

+1

After using the release system with 3 different 4.7 branches for my project, I can see how other module maintainers have taken advantage of multiple branches much more than anticipated. I think this has been a good thing.

I'm all for the new explicit "one obvious way" approach (very 'Zen of Python' like).

As an aside: I'm guessing there wouldn't be anything in the project module(s) stopping branches starting at something like DRUPAL-6--3 rather than -6--1 , correct? The reason for this possibly silly/redundant question is that the branch number could almost be used as a module version number independently of the Drupal version. eg DRUPAL-5--3 and DRUPAL-6--3 both contain the same featureset written to different Drupal versions, whereas DRUPAL-6--4 contains new features, and the Drupal 7 branches might start from DRUPAL-7--4. I already see some well maintained modules like Panels and Views taking this approach with trying to keep different version numbers roughly comparable across Drupal releases.

+1 from me if you think it's an improvmenet- this is, in a way, easier to remember anyhow.

this proposal is a nice improvement. i was one of those who kept using DRUPAL-5 branch for multiple releases. this policy would make it obvious that this is not proper.

Agreed. I released a couple of my modules in the DRUPAL-5 branch and this makes it obvious that it's not The Right Way.

It is a hassle for those of us who are used to CVS updating an entire copy of /contrib, for a particular branch of Drupal, but in the long run that is less and less helpful. The only REALLY valuable use case for it is grepping all of contrib to see if a core API change will break many modules. ;)

It is a hassle for those of us who are used to CVS updating an entire copy of /contrib, for a particular branch of Drupal.

This is the part that concerns me.

Right now, I checkout all of the contributions tag DRUPAL-5 in one directory, and do the same for HEAD and DRUPAL-4-7.

For my modules, I tag (but not branch) release tags from that directory (e.g. DRUPAL-5--1-1) and keep going. When the time comes for another release, I tag DRUPAL-5--1-2, then DRUPAL-5--2-1, ...etc.

The reason for going for tags and not branches is less complexity, and if I ever need to checkout a particular previous release, I can specify the tag that corresponds to the release, and can even branch on it if the need arises.

This saves me having a checkout for DRUPAL-5--1-1, DRUPAL-5--1-2, ... and DRUPAL-5--2-1 each in a separate directory.

This proposal has merits of course, and dww feels strongly about it. But it will complicate the scenario above, and N directories will be needed.

Sorry dww (and others who support this), but I am seeing that we are moving towards more complexity for the release system. At least too soon.

@kbahey -- sorry, don't take it personally, but you perfectly illustrate the confusion between branches, tags, releases, and release series that this proposal will help clarify. Furthermore, the example of how you're currently (mis)using branches further illustrates why this needs to be fixed. ;)

I know what tags and branches are as far as CVS is concerned. However, as implemented in Drupal, I could have you enlighten me! I could use another microwave session ...

A) Our CVS repository prohibits you from making a DRUPAL-5--1-1 branch. All official releases are always based on tags. So, you're not special -- everyone makes their official releases from tags, and no one should ever have to check out separate copies of all their release tags. You can always just checkout from a tag if you want the code from a specific release. This has been true since day 0 of the release system. Nothing about the current proposal changes this fact.

Glad to hear that it is as simple as the way I am using it, and it would not change.

B) This part of your message: "and can even branch on it if the need arises" is in fact dangerously wrong. :( Given your example, once you've started adding 5.x-2.* code and release tags (e.g. DRUPAL-5--2-1) to your DRUPAL-5 branch, if you ever need to make a DRUPAL-5--1-3 release, you're screwed. The contrib repo doesn't let you go back and add a DRUPAL-5--1 branch, since that's forbidden, since that's what DRUPAL-5 is for (ugh!). So, if there's a security bug in 5.x-1.2, your users are totally screwed, and must update to your new-feature-filled, unstable 5.x-2.* series, since there's no way (without a HUGE ammount of work) to undo everything you've incorrectly put in DRUPAL-5 branch that really belonged in HEAD or a DRUPAL-5--2 branch.

That was based on the (now faulty) assumption that releases should be branches, and not mere tags. Since that is not a valid way to use it (and I never used it that way), that is a moot point now.

C) Aside from the fact your use-case is wrong, it's confusing for other people trying to monitor contrib via CVS branches. All the docs and existing conventions (for good reason) tell you that "The DRUPAL-5 branch is for the 5.x-1.* series of any given contribution". However, if maintainers do it your way, if someone wants to check out the latest 5.x-1.* stable code for all of contrib, they're going to be wrong when they get to your modules, since your DRUPAL-5 branch doesn't follow the conventions and is full of 5.x-2.* or even later code.

Please, believe me, this new approach is more simple and most importantly less error-prone than what we have now. There should be no freedom in how you use the branch for your 6.x-1.* code. It should always be for 6.x-1.* code, and nothing else. There should be a 1-to-1 mapping of release series to CVS branches. This proposal achieves that. What we have now is chaos.

So, all you are proposing is that DRUPAL-6 (for contrib) should be DRUPAL-6--1, and (as happens today for DRUPAL-X) that should be a branch off HEAD, then everything after that would be a tag? That is fine by me. It means I need to do some adjustment to the auto checkout script that I have (since core and contrib have different tags), but that is minor. Up to here, there is no problem.

What I don't like is that DRUPAL-6--2 is forced to be yet another branch, and although its tag is shared with other contrib modules, there is no commonality between them except in name, and we suddenly have lots of branches each in a separate directory for code version DRUPAL-X.

Yes, I can checkout only my module and have N directories for it, for example:

DRUPAL-5/
  DRUPAL-5/DRUPAL-5--1/
  DRUPAL-5/DRUPAL-5--2/

DRUPAL-6
 DRUPAL-6/DRUPAL-6--1/
 DRUPAL-6/DRUPAL-6--2/
 DRUPAL-6/DRUPAL-6--3/

But, 2bits maintain some 24 modules (last I checked), and you can see how this can get out of hand.

I understand the motivation behind having each DRUPAL-X being a branch, but don't want that to be forced on everyone who does not need/like it.

Retroactively branching solves part of this (do it only if/when you need it).

And yes, I tried to reread the proposal(s) and got lost quickly. Part of the problem is that things have a lot of background/domain knowledge that is clear to you, but not to the masses (me being one of them). So, brevity helps. Cliff's notes version if you will for the unwashed masses.

The more people try to defend the status quo, the more convinced I am it must be overthrown immediately. ;) I only wish I was more confident and insistent on this point when first rolling out the release system and the DRUPAL-5 branches. Oh well, live and learn.

Well, I can understand that, but we are moving into an overly complicated system, and we will pay the price of that down the road in maintenance and flexibility.

I think Derek has successfully answered every possibly question => Make it so!

dww has answered many questions I had about the current implementation. I agree it's crazy we can't issue security releases off an older stable release.

Can you also clarify the following, please?

Can't we branch for each Drupal release (D6, D7, etc.) first THEN branch for each stable release of our modules (DRUPAL-6--1, DRUPAL-6---2)?

Suppose I have the branches:
DRUPAL-6--1
DRUPAL-6--2
DRUPAL-7--1
DRUPAL-7--2
DRUPAL-7--3
... each with their releases (tags DRUPAL-6--1-1, DRUPAL-6--1-2, etc).

If after having released DRUPAL-7--3-0, I want to backport a cool feature from the D7 series of releases to the D6. How do I create a new branch called DRUPAL-6--3 off the top of the D6 branch?

If I understand your proposal, it is not possible
(and until reading this thread, I thought this kind of thing was possible with D5, but I now understand how crazy the system was, so I agree that what's being proposed is an improvement).

Hmmm... to answer my own question (and save you a lot of typing), I think this is how we would have to do it:

After having branched DRUPAL-7--3, I would have to clean HEAD and take away all D7 code, and put instead the code from the top of the branch DRUPAL-6--2. Check that in (into HEAD). Backport the feature. Check in. Branch DRUPAL-6--3. Then restore the latest D7 code into HEAD.

Is this how we would have to do it?

It also means we wouldn't be able to check out a D6 branch, and keep up to date with a simple cvs update with the latest stable release compatible with D6.

Is there a reason why we can't two levels of branches?

Is there a reason why we can't have two levels of branches?

All I'm asking is to rename "DRUPAL-6" to "DRUPAL-6--1" to drive home the point it's the one and only place for the 6.x-1.* specific code. Everything else remains the same.

And this is a GOOD thing. It makes the distinction explicit and obvious and helps avoid a LOT of confusion. It's a happy thing.

I've ported VotingAPI to Drupal 6 already, and I'm confused about where I should put it, branch-wise. Let's make DRUPAL-6--1 official! ;)

I agree with dww. +1 to nixing DRUPAL-6 branch in favor of DRUPAL-6--1 branch.

kbahey: I understand the problem you're pointing out about trying to check out all of contrib. All I can say is that yes, about a year ago we made it much more difficult to just have a checkout of all of contrib, because each individual module within contrib can be branched a few different ways. I think dww's cvs_deploy.module can help alleviate that somewhat, by taking some of the burden off of you for figuring out what is checked out where.

But the fact remains that yes, the --2 and --3 branches took a feature away from you and gave a feature to me. However, I desperately, desperately needed that feature in order to maintain my modules properly. So when you say it makes maintenance harder, I disagree with you there; for me, it makes maintenance easier. What it makes harder is tracking. And IMO that's less important.

But the fact remains that yes, the --2 and --3 branches took a feature away from you and gave a feature to me. However, I desperately, desperately needed that feature in order to maintain my modules properly. So when you say it makes maintenance harder, I disagree with you there; for me, it makes maintenance easier. What it makes harder is tracking. And IMO that's less important.

As someone who's going to be rolling out multiple versions of a couple modules for multiple versions of Drupal, I can say wholeheartedly that the annoyance of not being able to check out all of contrib in one swoop is outweighed by the clarity of the maintenance tasks. w00t.

While I share Khalid's pain of not being able to (mostly) do straight checkouts and updates on the drupal-5 branch, I can see how getting everyone to manage their contributions in the same way is an excellent idea. Let's get a script working to checkout/update the latest stable or dev-branch releases - http://drupal.org/node/124661.

I support this!

Thanks dww for your answer. I must have tried the wrong way, but I'l try again in the future.

Everybody seems to support your proposal (even Killes above), so go ahead! :)
DRUPAL-6--N branches make sense.

Actually, my request for clarification was on topic, and was another symptom of the confusion that dww talks about.

looking at my notes, I was doing:
cvs tag -b DRUPAL-5
then within this branch, the following would fail:
cvs tag -b DRUPAL-5--1-0
hence my questions above.
I had read the documentation many times, and it's very possible I misunderstood bits of it. But never mind that.

Now, if I understand the reply I got, I would be able to do:
cvs tag -b DRUPAL-6
then within this branch, I would do the following:
cvs tag -b DRUPAL-6--1
finally, within that latter branch, I would create a release tag:
cvs tag DRUPAL-6--1-0

It is much more logical.

Sorry for coming late to this.

dww, I am not upset. I like the microwave. Good for headaches!

kbahey: What I don't like is that DRUPAL-6--2 is forced to be yet another branch

dww: Nothing forces this. You can use HEAD as your pseudo DRUPAL-6--2 branch until you actually need HEAD for something else. In fact, this is the recommended way I've clearly documented in the CVS handbook:

http://drupal.org/node/17570#HEAD

What I meant is this:

Currently, I start with DRUPAL-5 as a branch (not a tag). I am fine with this, since HEAD is isolated now. Ignore HEAD for now.

Now I decide to make a release. I created DRUPAL-5--1-0. Then I make some API changes, and want to have DRUPAL-5--2-0. I thought that DRUPAL-5--1 and DRUPAL-5--2 have to be branches, not just tags.

Your new proposal (correct me again) forces them to be branches (not just tags). Is that not so?

Right now, I am using -5--1 and -5--2 as tags, and will only branches if I need to go back and make changes in -5--1. Until then, I don't want to branch them (too many sandboxes!).

kbahey: and we suddenly have lots of branches each in a separate directory for code version DRUPAL-X

dww: I have no idea what this means. There aren't suddenly lots of branches.

I meant too many sandboxes (checkouts of a branch tag), one for each branch, for each module. If DRUPAL-5 is the branch, and everything below it (-5--1, -5--2, ...etc.) are mere tags, I don't need a sandbox for each of them. If they are branches, I need a sandbox for each, which gets too unwieldy.

Anyway, if you're objecting to the ability to have multiple branches for the same version of core, a) you're about 1 year too late complaining and b) the facts on the ground prove that this is a wildly popular feature put to great use by many maintainers, and there's no way to go back on that now.

I am not against branching on the same version of core. I am against "forcing" the MAJOR part of DRUPAL-CORE--MAJOR-* to be a branch (as opposed to a non-branch tag). If it is optional, I would not care. The motivation is to limit the number of sandboxes I need to manage.

In the scenario I prefer (no forced branching), I can just leave the old branch the way it is, and only branch it if I need to.

So, off HEAD, I do:

cvs tag -b DRUPAL-5 (now I have a 5.x branch).
...
cvs tag DRUPAL-5--1-0 (first stable release, no branching ...)
...
cvs tag DRUPAL-5--2-0 (API changes, no branching still ...)
...
cvs tag DRUPAL-5--2-1 (Fix or feature)
...
cvs tag DRUPAL-5--3-0 (API changes, no branching still ...)

Something happens and now I want to branch -5--2 off the tag I created for 5--2-1, say a security fix.

cvs rtag -r DRUPAL-5--2-1 -b DRUPAL-5--2-2 (or some other suffix)

Until I need the branch, I don't need the branch.

So, if you are not forcing branches within the same core compat, go ahead and do what you want.

The complexity I am talking about is that X has to be a branch, but Y must not be, ...etc. This is complexity. Part of it is necessary, part of it may not be so.

@merlinofchaos: I have not tried out cvs deploy, since for clients I always install from tarballs now, ever since update_status started working. It is manageable this way and has a new feature (notification of updates, ...etc).

Since that is the only change (effectively a rename of DRUPAL-CORE for contrib to DRUPAL-CORE-MAJOR), then go ahead and do it.

Everything else remains the same.

I read through the issue, and I'm OK with it. It makes sense. Sorry for the delay getting back to you guys. Move on with it! :)