Patch Release Maintenance in Subversion (SVN)
is a release of a set of changes to a previous TWiki release that fixes one or more problems with that release. Patch releases are released as complete packages for new installations and
cumulative packages with all the changed files since last major/minor release.
The idea is that an admin with a running TWiki installation can always simply copy the contents of a the package with the changed files on top of the installation without having to have installed all the previous patch releases that have been released since last major/minor release.
A major release is a release where the first digit in the version number changes. A minor release is a release where the second digit in the version number. Patch releases changes the 3rd digit.
This is the release process as defined at TWikiCommunitySummitRome2007
- All development of major/minor releases and all plugins is done in the MAIN branch.
- The first major/minor release is built from a new patch branch which is created soon after the release meeting agrees to declare feature freeze.
- It is a strict criteria that the new Patch branch is not created until ALL agreed features are implemented. We do not create the Patch branch in the middle of the implementation of complex features. This means that in the short period between declaration of feature freeze and the creation of the feature freeze the feature freeze also includes MAIN branch.
- In the period between the creation of the Patch branch and the minor/major release all bug fixes to Core and default plugins need to be checked into both MAIN and the new Patch branch.
- New features are only checked into MAIN. Checking in new features to MAIN is allowed again the minute the new Patch branch is created
- Each time an actual release is created (major/minor/patch) a tag copy is created in SVN.
- The naming convention:
More details on the release process
- The Release branch is always created from MAIN. All major development happens on MAIN which also holds the plugin repository. The Patch branch is only created to create a stable environment to create releases from. See the Release branch as the current stable release branch
- All bug fixes are always applied to the MAIN branch which will be the continuous development branch (and which also holds all plugins).
- Between feature freeze and release of first major/minor all bug fixes are applied to both MAIN and Patch branch.
- Patch releases (third decimal number) only contain fixes selected on the basis of these criteria:
- Security issues. Some risk is acceptable when implementing these. Urgency is important here.
- A bug is very severe and can cause a lot of trouble for the users and admins. Some risk is acceptable when implementing these.
- A bug is very common and annoying. Fix must be well tested for a while.
- Bugfix where code inspection and experience tells us that this bug could become serious
- A bug with a very simple fix with no practical risk.
- Document changes that resolve issues that can have significant impact on some users. Doc updates are considered safe.
- These kinds of changes will never be merged into the patch branch after a minor/major release and released in a patch release.
- Complex bug fixes with many lines of code and/or many sources files and not being a security issue or very severe bug.
- Changes to settings and preferences. Admins must be able to apply a the package with the changed files without worrying that settings are reverted.
- Any kind of enhancements or new feature.
- Changes to plugins that are not in the standard TWiki release package.
- If a bugfix cannot be merged from MAIN or to the patch branch because of conflicts, or an urgent security fix is needed, a special temporary fix may be applied to the patch branch instead.
- Patch releases consist of a full release package and an archive with all the changed files since last major/minor release.
Release branching timeline
| +-------TWikiRelease04x02x00 (tag of major or minor release)
| +-------TWikiRelease04x02x01 (Tag) Incl zip package is relative to 4.2.0
| +-------TWikiRelease04x02x02 (Tag) Incl zip package is relative to 4.2.0
| +-------TWikiRelease04x02x03 (Tag) Incl zip package is relative to 4.2.0
| +-------TWikiRelease05x00x00 (tag of major or minor release)
| +-------TWikiRelease05x00x01 (Tag) Incl zip package is relative to 5.0.0
| +-------TWikiRelease05x00x02 (Tag) Incl zip package is relative to 5.0.0
| +-------TWikiRelease05x00x03 (Tag) Incl zip package is relative to 5.0.0
All we need now is a build script that will generate an archive with only the changed files
relative to a given SVN
revision and we are ready to rock (begging)
Background for the process
During the life cycle of 4.0.X, we successfully released a number of hotfix releases which have been to the benefit of both users that got the urgent fixes, and the developers who could focus on the next release. On the other hand the hotfix scheme has added a 4th level to the release numbers. And the hotfixes were managed outside SVN
. We decided to change the process so that all fixes are handled in SVN
During the release of 4.2.0 we decided to feature freeze with one feature still in progress of being developed. This feature turned out more tricky and time consuming than expected causing the feature freeze to last for 3 months making it near impossible for developers not to break the feature freeze.
It was therefore decided at the TWikiCommunitySummitRome2007
that the Patch branch is created soon after the time of feature freeze and that the first minor/major release is created from the Patch branch. This should shorten the feature freeze period on MAIN to a few days.
It is still the policy that the Patch branch is discontinued when the next minor/major is released and a new Patch branch is created. The community is too small to maintain and stable and a develop branch in parallel.
Branches and tags are created using svn copy
create the release branch from which releases are built
svn copy http://svn.twiki.org/svn/twiki/trunk http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02 -m "Item90210: Creating a release branch for TWikiRelease04x02"
Merge in fix from trunk
We assume that you have a checked out version of the current Patch branch so you can test the merged fix before committing it to SVN
revision 7766 we have made an important update that fixes Item90210 which we want to merge to the current Patch branch.
Current working directory is the local checkout copy of the release branch
svn merge -r 7765:7766 http://svn.twiki.org/svn/twiki/trunk
Commit the changes
Put the Item90210 temporarily back into
state if it has been closed or waiting for release.
svn commit -m "Item90210: Important hotfix of bug xyz merged to TWikiRelease04x02 branch"
create the release tag after a release has been built and released
svn copy http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02 http://svn.twiki.org/svn/twiki/tags/TWikiRelease04x02x00 -m "Item90210: Creating a release tag for TWikiRelease04x02x00"
then copy the files from the created zip into a checkout, and commit (used to build the next lot of twiki topics)
Build the patch release
perl build.pl release
Create the diff (for getting the list of changed files)
svn diff http://svn.twiki.org/svn/twiki/tags/TWikiRelease04x01x00 http://svn.twiki.org/svn/twiki/branches/Patch04x01x02 > TWikiRelease04x01x02.diff
Create the zip and tgz of all the changed files
We need a scripted solution to this
-- Contributors: KennethLavrsen
Patch4x00 is now on SVN
with all hotfix levels.
- Copy of 4.0.4 - SVN 11604
- Hotfix 404-1 - SVN 11605
- Hotfix 404-2 - SVN 11606
- Hotfix 404-3 - SVN 11607
- Hotfix 404-4 - SVN 11609
No tags will be created for these old hotfixs. That will just confuse more than it solves. Next tag will be a release 4.0.5. Still need a scripted solution for making the zip and tgz with only the changed files and only those that are in the release package.
- 27 Sep 2006
Thanks Kenneth and Crawford for defining a patch release solution that is SVN
- 30 Sep 2006
Note that I have updated the process above based on what was agree in Rome August 2007. It is a rewrite so please read carefully.
With this new process the word Patch for the branch may be a little confusing. If there is a wish in the community we can name it Release04x02 instead. If enough people have this wish I will change the process.
- 20 Aug 2007
I presume that the pink diagram is a patch geneology, and not (as could be interpreted) a file layout.
I personally would rather that the name of each branch and each patch release, was the same as the name we give it on twiki.org.
And for that, I have a proposal
- Move MAIN back to /svn/trunk where it belongs. (optional, but would return TWiki into a more normal layout)
- call the release branch - TWikiRelease04x02
- tag each release with TWikiRelease04x02x00
This would result in Subversion having the following structure (not that
far from where we are now)
I do think the 'Patch04x02' name for the branch is odd :).
The real work to make this happen, is to make the Bugs system more able to allow pushing issues to later releases and tracking what needs to be merged into the release branch, and what needs to be merged out of it.
- 22 Aug 2007
- Yes, the pink diagram is a genealogy.
- I'm all in favour of a more sensible name for release branches; Patch04x01 was just historical. Your naming scheme makes perfect sense.
- I do not favour moving MAIN back to truck, just because of the havoc it would cause. Sheer laziness on my part.
- Targeting issues at specific releases is something I have wanted for a long time; the reason I have not pushed it is the fact that even with the current incrediby simple flow, people still get it wrong. It's very tempting to move the release assignation to a topic that can only be edited by the release team, and then %SEARCH for the current bug.
- 22 Aug 2007
Sven's branch naming conventions make perfect sense to me, and are more or less what most projects use (I gave the example of the FreeBSD release engineering
process in Rome).
- 22 Aug 2007
If we had x-zillion developers btw, we could make the step 3 (tag a release) also a branch. Because in Sven's proposal, if you are on say 4.2.1 and there is a security update, you are to upgrade to 4.2.x where x>1.
- 22 Aug 2007
I think Svens naming for the branches is great. So let is do that starting from 4.2.0. Ie next is called TWikiRelease04x02
And tag names like we have done all along
The patch name came from the fact that all patch releases are built from it. But for each minor/major release it seems a bit odd. TWikiRelease04x02 is a much better name and suits both the purpose for a major/minor release and the follow up patch releases.
I agree with Crawford that changing name to trunk just to be like everybody else has too high a price to pay. I would stay with MAIN which is also a fine name.
- 22 Aug 2007
This historical account has been updated to make the mini-tutorial correct for the post Feb 2008 svn layout, but makes references to the MAIN branch that has been moved to http://svn.twiki.org/svn/twiki/trunk/
- 17 Feb 2008