Thoughts on the P5 release process

1. MULTI-BRANCH STRATEGY

The multi-branch strategy is a good idea, but only if it's unrolled over a period of several days, something like this:

 - The release branches for Stylesheets and P5 (mutually dependent) should be created two weeks ahead of release day.

 - The VERSION file should be updated at that point in the release branch and the dev branch (putting dev a point ahead of release).

 - The release notes should be written and committed at that point.

 - The changelog should be generated at that point.

 - The Jenkins sysadmins should be asked to activate the branch build jobs.

This means that from the day of its creation, the release branch is intended to be ready-to-go. Then Council should have all eyes on it for at least a week. When a bug is found:

 - The bug should be fixed in dev first;

 - Then the commit should be pushed to the release branch. Documentation will have to explain how to cherry-pick a commit from dev and push it to the branch.

 - The changelog should be regenerated and committed on the release branch.

The release branches should be signed off by the release technicians as "ready" several days in advance of the release day. At that point:

 - The release branches should be merged into the master branches; then

 - The release branches should be deleted.

If all goes well, then nothing should break; the master branches should be building perfect versions of the releases, all ready to go. If further problems emerge, fix in dev and push to master. No third branch should get in the way.

In terms of the current TCW22, this gets steps 1-6 out of the way long before release day. It should then be much more straightforward to complete the release on release day.

Nobody cares whether the build date on the products is the same as the day when the release actually appeared and was announced. No more mad midnight releases and desperate hacking of datetimes!


2. TESTING RELEASE SCRIPTS

Every time we do a release, we painfully rediscover that the release scripts are somewhat mysterious, and every new release technician is running them for the first time in a real-life situation on a live server. This is mad and scary.

We should have, somewhere, a test setup which has the same weird filesystem paths as tei-c.org, and has copies of the release products. This would ideally be on a VM so we can easily roll it back to a snapshot before the release. We should be able to test [versions of] the release scripts to make sure they do what we expect them to, and to enable new release technicians to actually try them out before having to run them live. We should probably create this as a sort of VirtualBox appliance, so anyone can download it and try things out when they need to.


3. SOURCEFORGE AND GITHUB

SourceForge is currently our canonical release location, in that many of our scripts pull their content from the releases there. We should continue to release packages on SourceForge -- why not? -- but we should make sure that the canonical release locations are on GitHub, and scripts should be updated accordingly (including the oxygen-tei build script). The push of products to SourceForge should be a final stage when everything else is working.
 

4. CIRCULAR DEPENDENCIES

Some Stylesheets tests seem to depend on the release version of P5 (pulled of tei-c.org), while the P5 build depends on the Stylesheets. This circularity is very risky. If it's possible to rewrite the Stylesheets build so that it takes no account of P5, that would at least ensure the dependency works in only one direction.

TCW22 is written on the basis that Sebastian is dealing with the Stylesheets, and he will handle them at the end of the process (Step 19). In fact it's better to think of the two products as parts of the same release process, and the Stylesheets as the initial phase; Jenkins builds the Stylesheets first in the sequence, other things being equal, and the P5 builds depend on a working Stylesheets build from the same vintage. One of the release technicians should be familiar with the Stylesheets to some degree, and in general, I think it makes sense to coordinate releases. There's nothing to prevent interim releases of P5 or the Stylesheets independent of the other products (and both of these scenarios should trigger a new release of the Oxygen plugin), but I don't recall seeing a P5 release (other than a quick-and-dirty bugfix in the days after a release) that didn't have an accompanying Stylesheets release, so we should probably plan them together.