Forum OpenACS Q&A: Response to How do you separate project customisations from improvements?

Well, the projects I was on at aD had a very simple procedure for submitting bug fixes back to the core - we didn't. Now, my projects all happened to be late rather than early adopters of new ACS toolkits, so that may not be representative. But it did seem to be the standard procedure, unfortunately...

So, when it comes to how best to make changes so as to make it easy to contribute fixes back to OpenACS core, I'm offering my own speculations here, not any true hands-on experience.

And anyway, aD did not do this with any "clever shell scripts". Yes, there were some very simple shell scripts floating around for different projects, and there may have been some others I wasn't aware of, but there's nothing here you can just wave a shell-script wand at to make it go away.

FYI, you can find both some of aD CVS shell scripts and a bunch of info on CVS my personal web site. I wrote that CVS Policy and Howto document because I found it useful; I sure wouldn't mind hearing if other folks find it useful, too. :)

Changes can logically be thought of as two different types: A customization just to my codebase, or a change that I think should be rolled back into OpenACS - I will call these "customizations" and "OpenACS fixes". If you're careful to make changes of only one type of change in a single commit, you should always be able to go back in later and sort things out, in order to prepare a patch against the core OpenACS.

What you really, really want to avoid, is where you commit something extra by mistake, or otherwise mix different changes into a single commit. Because then, in order to fix bugs or prepare a patch, you have to figure stuff out at a finer grain than the CVS commits, and that is a royal PITA. You want to avoid this. So the standard CVS religion applies - always use cvs diff on your files before commiting, just to be sure what you're really committing is what you think you're commiting, etc. etc.

CVS is kind of a blunt instrument in some ways for doing distributed development, and some folks (Larry McVoy of BitMover) make fairly convincing arguments that their tools are technically superior. But CVS is what we have, and what OpenACS uses, and it can certainly do the job, so we'll all just have to learn to cope with it.

Note that if you've modified 5 files as part of a single logical change, you should always commit those 5 files with a single cvs commit command, and a single (descriptive) commit comment. This is because although CVS doesn't have genuine atomic commits, varius add-on tools like will use the fact that the commit comments are identical to simular atomic commits when generating GNU-stle changelogs and the like. So do your commits as if CVS commits are atomic, even though they're not.

Steve, your two branches suggestion makes sense to me. This might be most useful if you are doing a lot of changes, both customizations and OpenACS bugfixes.

I think, ideally, one way or another you must have your own separate "OpenACS fixes" branch. I say "ideally", because if you haven't made many of your own changes you can clearly get away without it, but let's say you've customized your own codebase quite a lot for some reason. Now, you find an OpenACS bug and fix it - great, it works! Except, how can you really be sure your fix also works in a stock OpenACS? The answer is, you can't, not without testing it on a stock OpenACS. So you need to set up a stock OpenACS for testing.

Merging aross CVS branches is definitely better than manually applying patches, so you certainly want to use branches. (If you did a proper CVS vendor import of the OpenACS code when starting your own project, this should be easy to do.)

So either you make changes to your own customized branch and then merge them into your "stock plus my fixes" branch, or you make changes to your "stock plus my fixes" branch, and merge them into your own customized branch. I don't see any particular reason to prefer one direction of merging over the other.

Clearly, if you are using a completely stock OpenACS and just adding your own packages, then maintaining a separte "OpenACS fixes" branch is a waste of time - you already have that. Thing is, everyone's going to have some customizatins, even if only to www/default-master.adp The more customizations you make, and the more OpenACS fixes you make which haven't made it back into the core, and then back out to you again in the form of a new OpenACS release, the more likely the separate "OpenACS fixes" branch is going to be worth having. I don't where that trade-off falls, though.

Now, on getting your OpenACS fixes back into OpenACS proper, I've still not contributed any code to OpenACS, so I can't say anything useful about that.

Your local "OpenACS fixes" branch is also the obvious place to frist merge in new releases of OpenACS, before you merge them into your customized codebase.