[development] How to develop and maintain your contribution (and use branches wisely)

[Derek Wright]

[I agree with Moshe -- let's not hijack my other message (which  
wasn't even meant to be a "thread", just an FYI) with all this talk  
about managing changes, releases, branches, etc...]

On Oct 25, 2007, at 1:52 AM, Karoly Negyesi wrote:

> DB and API changes must happen in a new branch. Any given branch  
> should not contain anything else but bugfixes just like Drupal core.

I believe chx has in mind a certain release of CCK that fundamentally  
altered the schema and API (of a module that dozens of others depend  
on), which just showed up as another official release in the 5.x-1.*  
"stable" series (i forget the exact version number).  The CCK  
developers have been sufficiently harassed about this in the past, so  
I don't want to re-open that discussion (or those wounds). ;)

Some things to keep in mind:

A) In general, chx is right: a stable branch of your contribution  
should remain stable, and only have bug fixes applied.  If you're  
adding features and/or changing the database schema, that should be  
happening in a separate branch, clearly marked as such, and people  
using releases from that branch should know what they're getting into.

B) Point (A) is *especially* important for API modules that others  
depend on.

C) Sometimes the only way to fix a bug is to change the schema or the  
API, so you actually have to use some judgement in each case.

D) I'm not sure about adding a "Schema change" term in the "Release  
type" vocabulary.  Let's continue this particular part of the  
discussion in the issue queue:
http://drupal.org/node/186623

E) This is all fairly subjective -- there are different approaches  
depending on the module, the maintainer, the user-base, etc:

For example, merlinofchaos seems to treat each official release of  
views on his "stable" branches almost like a whole new release series  
on its own.  He goes through the whole beta/rc process each time,  
gets lots of testing, etc.  So, he still adds new features, and  
sometimes even alters the schema (as per his message to the other  
thread).  views is probably the single most important contrib module,  
with literally 1000s of sites depending on it.  Because Earl is so  
careful, and because everyone has an interesting in helping him test/ 
debug new views releases, this system works pretty well, and allows  
him to not go completely insane supporting way too many different  
versions of the views codebase.  That said, if he's adding new  
features to 5.x-1.x-dev on the way to the 5.x-1.7 release, and  
there's a security bug in 5.x-1.6 he has to fix, he's in something of  
a bind, since there's no good way to quickly get a 5.x-1.7 out to  
just fix the security problem without also introducing potentially  
instable code from the new features he already added. :(  So, I can't  
recommend this as a Best Practice(tm), and it really only works for  
Earl since he's super-human. ;)  Also, he's careful not to commit new  
features that are "too big" on his stable series, and certainly not  
fundamental re-factoring of the API, schema, etc.

Other modules do what I'm suggesting as the default: they keep the  
5.x-1.* series for bug fixes, and work on new features and schema  
changes in the 5.x-2.* series.  New official releases on the 5.x-2.*  
series don't each require a bunch of beta/rcs, since everyone  
understands this is unstable code, and they shouldn't be building  
production sites out of it just yet.  Eventually, when the feature  
set settles down and the maintainer is happy, they can declare  
5.x-2.* stable, make that the official version, and start work on the  
5.x-3.* series to keep adding new features (or not, and say they're  
only going to start adding new functionality in the 6.x-2.* series  
once the current feature set is ported to 6.x and the 6.x-1.* stable  
series is out).

Sadly, I think many (most?) module developers aren't careful about  
this at all.  They just commit whatever they want to all of their  
branches (or don't really use branches at all).  This is  
unfortunate.  Most developers in this boat either plead ignorance  
("But CVS is Too Hard(tm), so this is my only choice") or laziness  
("I don't have time to maintain a bunch of different branches"). I  
can completely sympathize with both how intimidating CVS can be  
(especially if you're not used to revision control or release  
management), and how much work it can be to maintain something  
responsibly.

To address the ignorance, there is a lot of good (Drupal-specific)  
documentation about CVS in our handbooks and that learning this is  
time well-spent.  The hardest part is understanding the fundamental  
ideas of release management and branches, which is true across any  
version control system you'll ever use for the rest of your life.
http://drupal.org/handbook/cvs

In terms of the effort it takes to maintain different branches, there  
are ways to make this less time consuming.  Also, keep in mind that  
some extra care to maintain a stable branch that most of your users  
depend on will probably save you time in the long run -- instead of  
running around trying to deal with the increased support load  
generated by having people building sites with your unstable code.

There's lots more to say about all of this, but if I keep writing it  
here, chances are lower and lower people will read it. ;)  So, if  
anyone is going to be in the Bay Area for BADCamp, they should come  
to my workshop about exactly these topics:

http://badcamp07.org/07/sessions/how-develop-and-maintain-your-drupal- 
contribution

Even if you're not there, I plan to write up some concise  
documentation about all this, both as a handout for my talk, and then  
eventually as handbook pages on d.o.  Anyone who's willing to help  
with this task, please let me know (off-list), and we can coordinate.

Thanks,
-Derek (dww)