Space: Apache Connectors Framework
(https://cwiki.apache.org/confluence/display/CONNECTORS)
Page: Release Process
(https://cwiki.apache.org/confluence/display/CONNECTORS/Release+Process)
Edited by Karl Wright:
---------------------------------------------------------------------
h1. The ManifoldCF Release Process
ManifoldCF is a little harder to release than most software projects because it
has a fair number of connectors which are conditionally compiled. Thus, you
cannot do a full release until the required dependencies are installed on your
release machine. Luckily, for packages that are proprietary, stubs have been
created which allow you to skip the installation of proprietary libraries in
order to create a release.
Releases heretofore have been done on Windows (both US locale and Japan
locale), and thus we feel that the release process is fairly robust for that
platform. Batch scripts have been created that ease the process mightily. On
Linux there has been no such development; if you like, you can be the first
release engineer who wants to port the scripts.
h2. Branches and tags
For any release, there should be a release branch. This branch should be
created by the appropriate "svn copy" command from trunk. For example:
{{svn copy}} {{[https://svn.apache.org/repos/asf/manifoldcf/trunk]}}
{{[https://svn.apache.org/repos/asf/manifoldcf/branches/release-0.6-branch]}}
A major release will have its own release branch labeled with the release
number (e.g. "release-0.6-branch"). A minor release will continue in the
appropriate major release branch, and have the required changes pulled up from
trunk one at a time. Thus 0.6.1 would be released from "release-0.6-branch"
also.
When the time comes to build a release candidate, the release engineer should
make an appropriately-labeled copy of the release branch in the "tags" area.
For instance:
{{svn copy}}
{{[https://svn.apache.org/repos/asf/manifoldcf/branches/release-0.6-branch]}}
{{[https://svn.apache.org/repos/asf/manifoldcf/tags/release-0.6-RC0]}}
When the release is finally completed, the appropriate tag is then renamed to
be the release name, e.g.:
{{svn move}}
{{[https://svn.apache.org/repos/asf/manifoldcf/tags/release-0.6-RC0]}}
{{[https://svn.apache.org/repos/asf/manifoldcf/tags/release-0.6]}}
h2. Preparing release branch
After you create the release branch, you need to set its version and update
CHANGES.txt to be consistent with it being a release version. Here is the
checklist.
# Update the build.xml - change the version number to the the planned release
version ("XXXX")
# Update all the maven pom.xml files - "mvn versions:set -DnewVersion=XXXX"
# Edit CHANGES.txt to mark the release (convert "XXXX-dev" to "Release XXXX")
# Check in these changes to the release branch
h2. Before releasing
Before you cut a release, it's always a good idea to run all the tests you can
on the software. Also necessary is a "rat" run, which detects unknown or
incorrect licenses on source files. See the complete checklist below.
# Download the dependencies for building and testing (ant make-core-deps
make-deps). You will need svn 1.7+ installed for this step.
# Check licenses (ant rat-sources). You are interested in verifying that there
are zero files with unapproved licenses. (This comes at the very start of a
long report.) You will need Apache Rat installed for this step.
# Run standard integration tests (ant test-dr test-hs). If you have PostgreSQL
installed and MySQL, run those too (ant test-pg test-my).
# Run the UI tests (ant uitest). You'll need Python 2.7\+ for these.
If everything looks good, you're ready to go ahead and cut the release\!
h2. Building ManifoldCF for release
NOTE: In order to proceed, you MUST have svn 1.7 or higher installed\! The ant
build scripts require this in order to be able to apply patches on Windows
platforms. On Windows, you will also need GnuPG installed (from
[http://www.gnupg.org/download/]), and have your signing key created and
installed (read this: [http://www.apache.org/dev/release-signing]). Also needed
is the utility "pscp.exe".
The first step of the build process is to check out the release branch into a
work area. Technically it is more correct to check out the tag, but in
practice that's not necessary because only the release engineer should be
working on the release branch. All other development should be taking place in
trunk.
{{svn co}} {{[https://svn.apache.org/repos/asf/manifoldcf/release-0.6-branch]}}
{{myworkarea}}
Then, check out the Windows release scripts also:
{{svn co}} {{[https://svn.apache.org/repos/asf/manifoldcf/release-scripts]}}
The release scripts perform all the required fetching of dependencies
automatically, through ant. But they do not know how to deal with proxies, so
if you have a proxy you will need to figure out how to deal with that.
Next, you will need to create a place to put the release in your
people.apache.org public_html area. This directory should be named
"apache-manifoldcf-<release_name>". The release candidate will be copied there.
The next step is to fire off the release script itself. You will need to
supply your people.apache.org username also:
{{cd myworkarea}}
{{../release-scripts/release.bat 0.6 kwright}}
After being prompted a few times for your key file password, and for your
people.apache.org password, your release candidate should be created and copied
to an appropriate subdirectory in your user area on people.apache.org, e.g.
[http://people.apache.org/~kwright/apache-manifoldcf-0.6].
Finally, create a tag corresponding to the release candidate, as previously
described. Obviously release candidates should start at RC0 and count up
sequentially.
h2. Calling the vote
Once the artifact has been uploaded to people.apache.org, you should call a
vote to release the artifact. This involves sending an email to
[email protected], with the title "[VOTE] Release Apache ManifoldCF
xxxx RCnnn". In the vote email, mention where the artifacts can be downloaded
from (http://people.apache.org/~<username>/apache-manifoldcf-xxxx), as well as
the full svn URL of the tag you created
(https://svn.apache.org/repos/asf/manifoldcf/tags/release-xxxx-RCnnnn). The
vote must have three +1's from committers, and must be open at least 72 hours.
h3. If the vote does not pass
If the vote does not pass, this usually implies that fixes will be made and a
new RC created. Fixes usually are committed to trunk first and then pulled up
into the release branch using the "svn merge" command, e.g. "svn merge -c ZZZZ
https://svn.apache.org/repos/asf/manifoldcf/trunk";. Before the creating of the
next RC, you should also log into people.apache.org again, and move the old
artifacts from the public-html/apache-manifoldcf-XXX directory to
public-html/apache-manifoldcf-XXX/RCnnnn. Then, upload the new RC as before.
h3. If the vote passes
When the vote passes, you should check the artifacts from your public-html area
directly into the svnpubsub svn. *DO NOT REGENERATE THE ARTIFACTS - the
community has voted on them and they are the only legal copies you should
distribute.* Once that is done, you should also use "svn move" to rename the
artifact RC tag you created to remove the -RCnnnn suffix from it.
h2. Updating trunk post-release
Trunk must now be updated to reflect the fact that it now represents the next
release. There are three things you need to do in order to complete this step:
# Update the build.xml - change the version number to the next planned release
version ("XXXX-dev")
# Update all the maven pom.xml files - "mvn versions:set
-DnewVersion=XXXX-SNAPSHOT"
# Edit CHANGES.txt to mark the release and start a new line marking the end of
the next release ("XXXX-dev")
# Check in these changes to trunk
Change your notification preferences:
https://cwiki.apache.org/confluence/users/viewnotifications.action
