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