[development] Missing CVS branches in contrib -- peeve

[Derek Wright]

On Jan 2, 2007, at 5:25 PM, Metzler, David wrote:

> It seems to me that the docs conflict just a bit.

i hope not. ;)

> Every time you branch, it seems to imply that you're going to  
> maintain that branch for bug fixes, and I don't do that (don't have  
> time).

no, it implies "this is a set of code compatible with a given version  
of core, and only changes relevant to this version of core will be  
made here".  there's no guarantee that *you* are going to maintain  
it.  it's possible you'll do it yourself.  it's possible you'll  
nurture a team of developers around the module and one of them will  
be the designated "maintainer" of an older version (e.g. webchick  
used to be the dedicated 4.6 maintainer for OG).  it's possible  
you'll completely leave it alone, but maybe someone else can pick up  
the torch...  the key is that this is API-specific code, which is why  
it's on a separate branch from code that's ported to a different API.

> I will probably maintain head for the current stable version, and  
> when I decide it's time to port, I'll create a branch to maintain  
> bugfixes only in the prior stable release version, and continue new  
> feature development in HEAD.  Regardless as to how many branches I  
> create (cause the docs tell me to) I'm trying to see if I'm missing  
> something here.

the branches aren't *just* for your benefit.  i think that's what  
you're missing.  the other thing you're missing is that once you  
create a branch, it's both a bad idea, and quite a pain in the ass,  
to try to remove it. ;)  so, just because a DRUPAL-4-6 branch still  
exists doesn't mean it's being actively maintained.  when you move on  
to only supporting DRUPAL-5, the code in the DRUPAL-4-7 branch is  
still there, but you're not forced/required to maintain it.  however,  
with proper branching, it's at least *possible* for someone to  
maintain it if desired or needed.

> The only reason I bring this up, is that I've created a 5.0 branch  
> on my
> code that I will "never alter any code in" because the doc's suggested
> I'd be irresponsible if I didn't.

the docs are trying to encourage people to leave the stable branches  
stable (DRUPAL-5), and develop new features in a new feature branch  
(DRUPAL-5--2 or HEAD).  however, the very beginning of a "stable"  
branch isn't necessarily stable. ;)

> Shouldn't I have waited till 5.0 released before creating this branch?

you could have, but not necessarily.  maybe you wanted to port your  
existing 4.7.x functionality to the 5.x API, but otherwise, not start  
adding a bunch of new features at the same time.  in that case, you'd  
port the latest 4.7.x code to the 5.x API in HEAD, make a stable  
DRUPAL-5 branch off of that, and then work on new features, code  
redesign, etc, in HEAD.

> Is there a reason I shouldn't develop 5.x-0.1 in HEAD and then tag  
> new releases from that?.

not really.  if you're not adding *any* new features, and are only  
maintaining stable code with security updates and bug fixes, you  
could do it all in HEAD, instead of making a DRUPAL-5 branch.   
however, many people like to check-out from a given branch in CVS  
when setting up test sites or even live sites.  it's nice to follow  
convention, so people know what to expect.  and, even though the  
release nodes now force you to say what version of core they're  
compatible with, checkouts directly from CVS don't necessarily have  
the benefit of that.  so, using HEAD directly for a live site sucks,  
since HEAD today might be 5.x-core, but in a few months, it's now 6.x- 
core.  HEAD is a moving target, so it's a nightmare for people trying  
to use in live sites...  hence "responsible maintainers use proper  
branches".

> (I've already created a DRUPAL-4-7 branch to maintain my 4.7  
> compatible code in and created new releases from it). Am I being  
> "irresponsible"?  What am I missing here?

the irresponsible thing would be to start adding a bunch of new  
features or other unstable code to your currently supported stable  
branch.  just ask killes. ;)  if people are using your module, and  
build a site, and some security vulnerability is discovered in your  
contrib, you need to be able to release a new version everyone can  
upgrade to right away.  if the only code compatible with the 4.7.x  
API had a bunch of new features that might also break their  
production site, they're screwed, and it's all your fault.  so, if  
you're adding new features, do it in a different branch, so you can  
keep (at least) 1 branch stable, secure, and ready for upgrades at a  
moment's notice, and another branch (or HEAD) for new features and  
progress.

> Decide for yourself whether you think this is in conflict:
>
> On the one hand......
> http://drupal.org/handbook/cvs/branches-and-tags/contributions
>
> Once a contribution has been ported to a given version of the Drupal
> core API, the maintainer should create a branch that matches the  
> branch
> name used by core. This is not technically required, but is definitely
> recommended for responsible project maintainers. These initial stable
> branches have the exact same format as Drupal core branches, for  
> example
> DRUPAL-5 or DRUPAL-4-7.

right, this is saying "by convention, once your code works with the  
new version of core, make a stable branch and leave it stable so that  
folks can build production sites with it".

> On the other.....
> http://drupal.org/node/17570#HEAD
> Eventually, you'll decide it is safe to update the module to the next
> version of core. At this point you should make a new branch for your
> previously developed features, before you start porting to the latest
> version of core. Once that branch was created, you would convert your
> module in HEAD, and when you consider it stable enough for an official
> release, you would create a new stable branch that was compatible with
> the new version of core.

yeah, sorry, this is slightly confusing.  you need to read the rest  
of this section for this particular bit to make sense. :( the  
previous few sentences you didn't include say:

"Any bug fixes you make in your current stable branch should be  
committed to HEAD as well. Additionally, new features or any major  
changes to your code should be developed directly in HEAD. You can  
tag official releases in HEAD, but identify them as the development  
series for the previous version of core."

it goes on to give an example to show what i'm talking about:

"For example, during the entire period when the 5.0 release was being  
developed, the HEAD of your module would remain compatible with the  
4.7.x core API. Any bugs you fix on the DRUPAL-4-7 branch would be  
committed to HEAD, but you would also add new features and do other  
major changes there. Once you had a set of new features working well  
enough to release, you would add the DRUPAL-4-7--2-0 tag to a  
workspace checked out from HEAD and submit a release node pointing to  
this tag (which would be version 4.7.x-2.0). Time goes on, and you  
add more features, so you create the DRUPAL-4-7--2-1 tag for the  
4.7.x-2.1 release and so on. At some point, you feel like the 5.x  
core API is stable enough to port your module to, so you add the  
DRUPAL-4-7--2 branch off the end of HEAD so you could continue to  
make 4.7.x-2.x releases if you needed to (for example, to fix a  
security hole in the 4.7.x-2.2 release). Now, you can update your  
module, and when it is stable, you add a DRUPAL-5 branch and start  
the whole process over again as the Drupal core 6.x API is developed  
in the core repository's HEAD branch."

i know i wrote it all, so it all makes perfect sense to me, but that  
doesn't seem to contradict the previous thing about "make the  
DRUPAL-5 branch when you have stable code and leave it stable" at  
all. ;)  feel free to make concrete suggestions for improvement...

> Thanks again Derek for the new release system... I am loving it!

glad to hear it!

cheers,
-derek