Adempiere Release Management
Needs alignment with new release strategy
- 1 Some basic rules of release management in Adempiere project as of 3.4.x releases
- 1.1 History
- 1.2 Basic principles
- 1.3 Operative example of Release Branch (3.4)
- 1.4 Stable branch commit rules
- 1.5 Release Management Illustration
- 1.6 Merging bug fixes to the trunk
- 1.7 Question And Answers
- 1.8 References
- 2 See Also
Some basic rules of release management in Adempiere project as of 3.4.x releases
In the start of Adempiere, developers agreed that release should be done based on functionality and that Trunk version in SVN should be kept "production stable" at all times.
While this model is nice to developers it is quite troublesome for implementors, as they don't have long term production ready releases with enough bug fixes.
So some of us proposed new so called time based release management strategy and been given green light to go with it for upcoming 3.4.x releases.
For time based release management basic principle is, that at some point in time we decide and make so called Release Branch. This release branch is spin off of main development which is happening in trunk.
Release branch main goals are:
- to provide place for stabilization
- to provide place for QA
- to provide long lived place for bug fixes in the life of stable release branch.
After creating stable branch some activites are necessary on the path to stable release:
- stabilization of the code in form of BUG fixes (Bug Days)
- QA testing in form of real or simulated implementation
- disabling of not functional parts of code/AD
This period should not be too long, as current trunk seems to be quite stable. However there are some areas of new functionalities that should be either disabled or fixed before first stable release (tag), as they do not work and can cause problems with too adventures end users.
Stable Release Tags
Stable releases are based on stable branch. At some point in time, when most of bugs and QA have been done we should make stable release.
Stable releases are technically tags in which NOBODY should commit. So they are snapshot of code at given time.
All bug fixes are still maintained via Stable Branch.
First stable release should be done for example 7-14 days after creation of stable branch, with preferably at least one Bug Day in that period.
Operative example of Release Branch (3.4)
On Wednesday 20.02.2008 we are opening release branch:
Please be advised, that branches should never have release numbers like 340, 341, and so on. We have only one stable branch 3.4 for all 3.4.x releases.
This branch is effectively copy of trunk at that point of time.
Now we are in the point of stabilization and QA before actual first release.
What should developers do first
At that time, developers should first create necessary adjustment to code, that would allow users to install from scratch:
- Prepare and commit databases DUMPs <- only this is acctualy mandatory
- Change information about code release to adempiere_3.4.0 <- Here we already prepare for the first release
This should be done as soon as possible as QA testers usually are not enough skilled with the code and we surely want to attract as many testers as we can.
Once we have those basics set, QA testers can start their job finding bugs and not worked functionality.
What should QA testers do
QA testers should now check out this stable branch branches/adempiere34 and make their installation based on this code base.
- Every bug should be reported to sf.net bug tracker and marked as 3.4 bug
- Every not working functionality should be reported to sf.net bug tracker also
- Report success with new functionality on the forum ?
First Stable Release of Stable Branch
After at least basic QA testing and bug fixing, we should make first stable release.
In our case this would be Release: tags/adempiere340 (Adempiere 3.4.0)
If we are lucky and no DB changes were neccessary (not likely) we can just copy current 3.4 branch to release tag and be over, but this is unlikely.
So before making releases developers should prepare Databases dumps.
Consecutive operations on Stable Branch
After first stable release, users will still found bugs in day to day operations.
Such bugs have to be resolved in stable branch and as soon as possible transfered also to trunk.
Procedure for developers is as follows:
- check out from stable branch branches/adempiere34
- Create installation (best way with alternative (DB/DBusername)
- Replicate bug
- Fix bug
- Commit to stable branch
After fixing bug, developer can go back to do development on trunk version.
When enough bug fixes is collected, there is a time for new stable release. Once again developers should prepare database DUMPs and release number corrections and stable branch can be copied to stable release/tag: tags/adempiere431
This cycle is repeated, until there are production use and bug fixes for this stable branch.
Stable branch commit rules
For time being I would like to ask, that only bug fixes are made on stable branch. All new functionalities should be made in trunk. If we can achieve the goal of often releases there will be no need to put any functionality and enhancement into stable branches.
In the long run however, there can be change in this policy, if we fail to release often enough. Than some minor enhancement could be aplied to stable branches as well.
For time being this rules should be applied to code for stable branch:
- No file moving around
- Changes isolated to one bug fix and as minimal files concerned as possible
- Not working features (which do no harm) should be disabled for user, but no code change is desired
- Minimal or no code refactoring, just really necessary
Let's keep stable branch as stable as possible, new stable branch is just around the corner and all new exiting features will have the chance in next release (please do use trunk for new development).
Release Management Illustration
Since one picture can replace 1000 words:
- Trunk is main development pool, here all normal development takes place
- At some point in time we split Stable Branch for preparation of stable release
- RED part is for developers, to prepare DB seeds, release names, etc ...
- YELLOW part is QA testing/bug fixes time in preparation of first stable release
- GREEN line is Stable Release time (e.g.: tags/adempiere340)
- DARK GREEN is normal production use and bug fixes as they shows up
- second GREEN line is next Stable Release time, when enough bug fixes are collected that it makes sense.
- Experimental BRANCH is for experimental development. It my or may not be actually valid or useful, so we make specail branch. But eventually any experimental branch should be either discarded or included into trunk. If not we have a fork !
Merging bug fixes to the trunk
I believe it would be wise to have common practice how to merge bug fixes from stable releases to trunk.
It was suggested that bug fix merging should be done in at least weekly manner, which sound reasonable.
Procedure for BUG fixing should look something like this.
- At the time of releasing stable branch this branch would have release number e.g. 4738
- We are fixing bugs and committing to the stable branch.
- At the end of the week trunk maintainer decide to merge fixed bugs to trunk
- She should define current revision number of the stable branch, let say it's 4888
- She should have current clean trunk checkout on hand
Now we have all information needed to perform our merge:
svn merge -r 4738:4888 https://adempiere.svn.sourceforge.net/svnroot/adempiere/branches/adempiere34
Working copy of a trunk should now have all bug fixes merged. Of course maintainer should now check for conflicts and functionality of the trunk (compile, instal, ...). If everything will work as expected he can commit changes to the trunk.
BUT now there is very IMPORTANT administrative part of the process.
Revision 4888 (current stable release branch revision) should be noted on wiki page, so next merge will do just bug fixes made after revision 4888.
For example. If next week revision on stable branch is 4965 one would do in his clean trunk checkout:
svn merge -r 4888:4965 https://adempiere.svn.sourceforge.net/svnroot/adempiere/branches/adempiere34
And have latest bug fixes merged, and of course noted latest merged revision 4965
Question And Answers
I suppose there will be some question about operations and so on. Here should be a place to answer such questions. Details may be discussed on forum but rules should be written here.
How about migration sql scripts ?
There will be times, when bug fixes will require some migration SQL scripts to be executed. Question is, how we should handle those scripts when merging bug fixes into trunk ?
We now have: migration/330-331b migration/331b-trunk -> this would presumably go to migration/331b-340 I suppose it would be right to make: migration/340-341 right after release of 3.4.0 Here we would have SQLs applied for bug fixes
This will satisfy production users of stable release.
But question remain, how we would transfer those to trunk, should we mark what is from stable branch ?
I believe that those SQLs should be migrated to trunk as separate, but marked as "coming from stable branch" SQLs in trunk.
Question in my head is, how would someone, who uses stable releases and applies all SQLs in stable perform migration to next release (3.5.0). It is obvious that he will have some SQLs already applied, from maintaing stable release to latest stable version. Could we make problematic situation, when applaying SQLs would do some harm to DB ?
Doesn't this approach means more work for developers
Unfortunately yes. For fixing bugs in Stable Branch, developers would now have to check out stable branch, create stable branch environment and fix bugs. Then they would have to commit bug fix and only after that they could go back to trunk development.
But, this is I assume actually the same as we all doing right now on implementations. Difference will be, that we will all have basically the same environment, so more developers could replicate and fix the problem/bug.
And I hope we will attract many more end users, so our testing base will expand.
Original SVN book on branches scroll to subtitle Common Branching Patterns/Release Branches