Menu
▾
▴
Release-HOWTO
OpenSAF Release HOWTO
This is an instruction for the person acting as OpenSAF release manager; it
describes how to release OpenSAF according to our continuous delivery
process. Note that you should not attempt to create an official OpenSAF release
unless you are the designated OpenSAF release manager!
The OpenSAF project uses the Continuous Delivery for its releases. The aim is to
release OpenSAF once every few months. There is no need for any release planning
or feature freeze, so the decision to release OpenSAF can be made independently
of ongoing feature development.
The instructions below assume that no new commit is pushed by anyone to the
develop branch while the release is in progress (or more specifically: between
the time when the tests were run on the develop branch and the time when the
release notes and changelog have been pushed to the develop branch). This is
usually not a problem in practice since the OpenSAF git repository does not
receive a large volume of commits. It could be a good idea to create the release
outside of normal office hours though. If you experience the problem that
commits are pushed to the develop branch during the release process, you may
have to temporarily close the develop branch for new commits. This can be done
by making an announcement about it on the opensaf-devel mailing list, and
possibly also by temporarily restricting push access to the git repository by
changing the access permissions.
It is important to be careful and avoid mistakes when releasing OpenSAF, as it
would be embarrassing and seem unprofessional to produce broken releases
(e.g. the wrong version of the code was released, the code doesn't even compile
or crashes immediately when started, etc.). Less embarrassing (since it is not
so visible to OpenSAF users), but still serious, is if you mess up the GIT
repository.
When editing text files like README and NEWS, you should keep a maximum line
length of 80 characters where possible. This is easy using the M-q key
combination in emacs, if you have configured the editor according to the
[Emacs] instructions on the OpenSAF wiki. These instructions contain some
extra steps that may seem a bit unnecessary, but they are intended for extra
safety to double-check that everything is correct.
The notion 5.YY.MM is used in the instructions to denote the OpenSAF version
that is going to be released, 5.yy.mm to denote the previous OpenSAF release,
and 5.ZZ.XX to denote the expected next release.
Check out the develop branch and verify its test status
First, double check that your $HOME/.gitconfig file contains the proper
[GIT] configuration according to the OpenSAF wiki.
Checkout the develop branch and ensure it is up to date and tested, using the
following commands in an already existing clone of the OpenSAF source code
repository:
git checkout develop git pull git rev-parse develop
The third command above prints the latest revision on the develop branch. Either
run all the CI/CD tests manually on this revision or check that it has already
been tested and that all tests passed, i.e. that it was a GREEN run and the
tests were run on exactly the same GIT revision as you see when you run the git
rev-parse command. If something has been pushed on the develop branch after the
last test has been run, you cannot release OpenSAF until the tests have been
re-executed on the latest revision!
Just to double-check, run the build and unit tests on the revision you intend to
release:
./test.sh
Ensure that the OpenSAF version is correct
The README and configure.ac files at the top of the OpenSAF source tree should
contain the version number of OpenSAF that you are about to release, in the
format 5.YY.MM or 5.YY.MM.X, where YY is the current year, MM is the current
month and X is a minor version used for maintenance releases (.X is left out for
enhancement releases and sometimes also for maintenance releases if no
enhancements release has been made earlier the same month). The version number
in README and configure.ac (and later on also in ChangeLog, which is created in
a later step below) shall always be the same and YY and MM shall match the
current year and month when you are creating the release. The minor version .X
is added when a release has already been made earlier during the same month. You
should check that all occurrences of the OpenSAF version (there can be several
in the same file) are correct in both README and configure.ac. If they are not,
open the files in a text editor and change all occurrences of the OpenSAF
version (use the editor's search-and-replace function) to the correct one. Add
the minor version .X if another release has already been made during the same
month, and remove it if not. Note that the minor version .X is intended to be
used for maintenance releases containing bug-fixes only, so if enhancements have
been pushed to the develop branch you should consider postponing the release
until the following month. If the fix is urgent you may have to release a minor
version containing enhancements, though.
Write the Release Notes
The major manual effort when creating an OpenSAF release is to write the release
notes. Spend enough effort on the release notes to ensure that it is well
written. It is an important document describing the new, user-visible features
that have been added to OpenSAF since the previous OpenSAF release, as well as
minimum system requirements for the new release and special upgrade instructions
(if any).
Edit the file NEWS at the top of the OpenSAF source code tree. As already noted,
you should keep a maximum line length of 80 characters in the file. Search and
replace 5.yy.mm with 5.YY.MM in the NEWS file, and change the release date at
the end of the very first line in the NEWS file to today's date. Check that the
minimum system requirements in the first section are up to date, and adjust them
if necessary. If there is something special that the user should be aware of
when upgrading to the new version of OpenSAF, mention this below the system
requirements. Both the system requirements and the upgrade instructions are also
present in the README file, so if you have updated any of these two sections in
the NEWS file you must also do the same in the README file. Even if you haven't
updated them in the NEWS file, it could be a good idea to use the editor's
copy-paste function to copy both the minimum system requirements and the special
upgrade instructions from the NEWS file to the README file, to ensure that they
are identical (if you just look at them on the screen, it is easy to miss that
some number somewhere is different).
Below the system requirements section and the special upgrade instructions is a
chapter containing Important enhancements in this release. There is a
subsection for each OpenSAF service in this chapter, and for each service there
is a bullet list with enhancements that have been made. Note that only
user-visible enhancements shall be listed here. Bug-fixes and enhancements that
are not visible to OpenSAF end-users (i.e. so called internal enhancements)
should not be mentioned in the release notes! At the end of each bullet there is
a list of tickets that were implemented as parts of the new feature.
You should remove the old list of features that were implemented for the
previous release and add descriptions of the major features in the new
release. To get a list of implemented enhancement tickets, you can use the saved
search named 5.YY.MM Enhancements in the ticket system, or use the URI at the
end of the NEWS file. Note that this list also contains open tickets that have not been
pushed. Obviously they should not be in the release notes.
If no user-visible enhancements have been pushed to the develop branch since the
previous OpenSAF release, it means that you are in fact about the create a
maintenance release. For maintenance releases, the NEWS file is left untouched;
not even the OpenSAF version or release date at the top of the file shall be
modified. If you are about to create a maintenance release and no enhancements
release has been made earlier during the same month (i.e. you don't have to add
the minor version .X), then consider postponing the release until some
enhancement has been pushed.
The completed release notes in the NEWS file shall be stored both in the GIT
source code repository as well as on a page named NEWS-5.YY.MM on the OpenSAF
wiki. Note though that you should not publish the wiki page until you are done
with the rest of the tasks needed to create the OpenSAF release, so that all the
artifacts related to the release are published more or less at the same time.
Create the ChangeLog
The file ChangeLog at the top of the OpenSAF source code tree shall be prepended
with a list containing the short (one-line) description of all the commits since
the previous OpenSAF release. The following shell command can be used to
generate this list:
git log --pretty='format: * %s' 5.yy.mm..develop | grep -v ' release: '
It will exclude all the commits with the prefix "release: ", since these commits
are related to the release process itself and thus not so interesting from a
user perspective. The latest commits shall be at the top of the list, and the
oldest ones at the end. Add the output from this command below a header
containing the OpenSAF version number and release date at the top of the
ChangeLog, without deleting the previous entries at the end of the ChangeLog
file.
The completed release notes in the ChangeLog file shall be stored both in the
GIT source code repository as well as on a page named ChangeLog-5.YY.MM on the
OpenSAF wiki. The only difference between the ChangeLog in the repository and on
the wiki is that you should remove the leading space from all lines in the wiki
page. You can do this easily in emacs using the kill-rectangle command. Note
though that you should not publish the wiki page until you are done with the
rest of the tasks needed to create the OpenSAF release, so that all the
artifacts related to the release are published more or less at the same time.
Commit the updated ChangeLog, together with NEWS, README, and configure.ac (if modified)
Run the following command and double check that you have made the changes on the
develop branch:
git branch
Commit the changes made to NEWS, ChangeLog and README (if modified). The commit
message shall have the prefix "release: ":
git commit -m "release: Update NEWS, README and ChangeLog for OpenSAF 5.YY.MM" git push origin develop
Note: if you fail to push because something else has been pushed while you were
creating the release notes or ChangeLog, you have to go back to the beginning of
this instruction (re-test the latest revision and create a new ChangeLog
containing all the changes).
Merge develop to master and tag the release
When creating a release, there are only two possible GIT merges that you shall
do: from develop to master and from develop to release. First merge develop to
master and create a tag using the following commands (the --ff-only flag is
important):
git checkout master git merge --ff-only develop
If the merge fails because fast-forward is not possible, then something is wrong
with the repository. Maybe some developer has pushed to the master branch by
mistake. If this happens (it shouldn't), reset the master branch to the latest
release tag and re-try the merge.
If the merge was successful, tag the release:
git tag -a 5.YY.MM HEAD
Enter the following description for the tag (replace YY, MM and DD):
OpenSAF 5.YY.MM (released 20YY-MM-DD)
Finally, push the master branch and the tag:
git push origin master 5.YY.MM
Merge develop to release
git checkout release git merge develop git push origin release
If you get merge conflicts then resolve them in such a way that the release
branch will contain the exact same code as the current release you are about to
create.
Prepare the develop branch for the next release
git checkout develop
Open README and configure.ac in a text editor, and then search and replace the
release number 5.YY.MM with the expected version of the next OpenSAF
release. Typically, the OpenSAF shall have an enhancements release every few
months so the next expected release should be a few months (maybe two?) after 5.YY.MM.
Commit the changes, and push them to the develop branch (5.ZZ.XX refers to the
next OpenSAF version):
git commit -m "release: Update README, configure.ac for OpenSAF 5.ZZ.XX" git push origin develop
Create the source code tarball and upload it
Create the tarball (compressed tar archive) containing the OpenSAF source code
using these commands at the top level of the GIT repository:
git clean -dfx git checkout 5.YY.MM ./bootstrap.sh ./configure make dist
The tarball will be created in your local repository at the top of the source
tree. Test it by uncompressing, building and installing it:
tar zxf openaf-5.YY.MM.tar.gz cd opensaf-5.YY.MM ./configure make -j 4 make install DESTDIR=/tmp/osaf-install
Upload the source code tarball to the releases directory in the files area at
SourceForge. You will find the releases directory here:
https://sourceforge.net/projects/opensaf/files/releases/
Set the newly uploaded tarball as the default download for all platforms; you do
this by clicking on the "i" icon to the right of the uploaded file, and then on
"Select all" and finally "Save".
Tag the documentation and upload it
First, double check that your $HOME/.gitconfig file contains the proper
[GIT] configuration according to the OpenSAF wiki.
At the top of the documentation GIT repository, enter the following
commands:
git checkout master git pull git tag -a 5.YY.MM HEAD
Enter the following description for the tag (replace YY, MM and DD):
OpenSAF 5.YY.MM (released 20YY-MM-DD)
Push the tag:
git push origin master 5.YY.MM
Create a tarball containing the OpenSAF documentation:
git checkout 5.YY.MM tar --owner root --group root --numeric-owner -zcf opensaf-documentation-5.YY.MM.tar.gz *.odt
Upload the documentation tarball to the docs directory in the files area at
SourceForge. You will find the docs directory here:
https://sourceforge.net/projects/opensaf/files/docs/
Create new milestone and move remaining open tickets
Now we have to update the OpenSAF ticket system at SourceForge. In the Tickets
tab, click on Edit Milestones to the left. Click "Add Milestone" at the bottom
of the page and add the new milestone 5.ZZ.XX (which should be the same as the
next expected OpenSAF release that you wrote in README and configure.ac on the
develop branch in the step above). Set new milestone as default by clicking on
the bullet to the left, and enter an expected release date some time during the
month when the release is expected to happen (e.g. the 15th of that
month). Click Save.
Next, click in the field Search Tickets at the top left and enter the following
search query. Replace YY.MM in the query below with the milestone that was used
for the current release. Usually YY and MM are the current year and month, but
since the milestone was created when the previous version of OpenSAF was
released, the time of the next release was only a guess. If you had to edit
README and configure.ac at the beginning of this HOWTO because the OpenSAF
version was wrong on the develop branch, then the milestone is probably also
wrong (and you have to rename it later on in this instruction).
status:(accepted assigned unassigned review) AND _milestone:5.YY.MM
Click on Bulk Edit (not Bulk Move!) at the top right. Set the Milestone field at
the top left to the new milestone you just created, and leave everything else as
no change. Click Save. The change will be performed by SourceForge in the
background, and SourceForge will notify you when it is done using a notification
at the top left in your web browser. You may have to click somewhere (e.g. a
tab) for the notification to show up. Wait for the notification before you
continue.
After you have received the notification, go to Edit Milestones again and edit
the milestone for the OpenSAF release that you are creating now (probably
5.YY.MM) by clicking on the icon with a pencil at the end of the line. If the
milestone had the wrong name (wrong month) then change the name of the milestone
to match the current year and month. Also change the description text in this
case. Change the status from Open to Closed, and set the Due Date to today's
date. Click Save at the bottom of the page.
Finally, click on Edit Searches at the top left of the page and edit the 5.YY.MM
search by clicking on the pencil at the end of the line. Change the name of the
search and the milestone in the search query to the next OpenSAF release
5.ZZ.XX. Click Save at the bottom of the page.
Announce the new release on the opensaf-users list and on SourceForge
First, make sure you have completed all the previous steps and in particular
uploaded the release tarballs to the File area and the release notes and
ChangeLog to the wiki. It is then time to announce the availability of the new
release in a blog entry on the OpenSAF page at SourceForge as well as on the
opensaf-users mailing list.
Go to the News tab at SourceForge, which you can find here:
https://sourceforge.net/p/opensaf/news/
Click on New Post and write an announcement message. As a template you can use a
previous announcement and just replace all occurrences of the OpenSAF version
number. If it is an enhancements release you can use this previous announcement
as template:
https://sourceforge.net/p/opensaf/news/2018/04/announcement-of-the-opensaf-51804-release/
If it is a maintenance release you can instead use this post as a template:
https://sourceforge.net/p/opensaf/news/2017/11/announcement-of-the-opensaf-517111-release/
Once completed, click on Post at the bottom of the page.
Similarly, you can use previous posts on the opensaf-users mailing list as a
template. Here is one for an enhancements release:
https://sourceforge.net/p/opensaf/mailman/message/36298966/
Here is one for a maintenance release: