UIMA project logo
Notes on Releases with Git
Apache UIMA

Search the site

 Suggested basic release flow

  1. Update the master in preparation for the release, including things like the Readme, release-notes, the Jira release pointer for ISSUES Fixed, API compatibility: previous version. See checklist-release

  2. (optional, but recommended) Make a release branch, and do all the work on that branch. Once the release is out, merge the branch back into the master (should have very little change, other than new pom SNAPSHOT version levels).

  3. Checkout the release branch, and run the normal maven release prepare / perform cycles.

  4. Once the vote passes, retag the last rc with the rel/tag-name (see below).

  5. If branched, merge the release branch back into the master (updating the pom SNAPSHOT version numbers).

Git Commands to use

Make new Release branch

On github.com/apache/uima-xxx, use the website to create a new branch, suggested name rc/uimaxxx.x.y.z. Don't use a name starting with rel/ because those branches are "protected".

First switch to the particular "master" (e.g. master or master-v2 or ... ). Then create the new branch, which will start by being a copy of whatever branch github was on.

Check out the new release branch

Checkout a new release branch to a specific spot.

cd to your build spot; mkdir build-directory-rcX

git clone -b rc/uimaxxx.x.y.z https://github.com/apache/uima-uimaj build-directory-rcX

 Tags

Tags are stored in the .git folder in the subfolder /refs/tags.

When Apache Infra sets up a writable git project, they set github protection. The protection is set on

  • refs/heads/trunk
  • refs/heads/master
  • refs/heads/rel/
  • refs/tags/rel/

After a release passes, make a new tag for the release with the name rel/...tag-name... Here's how:

  • git tag -m "proj-name-1.2.3 rcXXX released" rel/proj-name-x.y.z proj-name-x.y.z^{} The strange notation ^{} peels the annotated tag and returns a ref to the actual commit.
  • git push origin rel/proj-name-x.y.z This updates the new tag to the remote repo

 What the maven release plugin does with GIT

release:prepare

  • Take all the poms in the project which start out at some x.y.z-SNAPSHOT version, and update the versions to x.y.z (without the -SNAPSHOT).
  • Build the project.

  • Create a commit with all the updated POMs, and commit that to whatever branch was checked out at the start.
  • git push
  • Create a tag
  • git push

  • Update all the poms to x.y.z + 0.0.1 -SNAPSHOT, and commit them
  • git push

release:perform

This does a build using the "tag" checkout, and uploads the artifacts to the maven staging repository.

The tag is cloned into the target/checkout directory

A build is done from the target/checkout spot, with maven artifacts uploaded to repository.apache.com staging area.

 How to roll back a release attempt

(Optional) Reset the branch to last commit before release:prepare

If you don't do this, when you do the release:prepare again, it will increment the SNAPSHOT and release numbers, and you'll need to override those. It's fine to work this way, as long as you remember to override the release and SNAPSHOT numbers.

The idea is to reset the branch being used to build, back to the commit just before the maven release:prepare commit, which is identified with the message [maven-release-plugin] prepare for next development iteration.

Do this by working in a checkout of the branch being used to build, typing git log ... and finding the hash for the commit right before the prepare commit.

Don't do this next step unless you know no one has fetched the previously pushed maven release changes. This is typically true, because only you are working on the release, and you typically will be working in a branch made just for this, which others are unlikely to access.

  • git log -5 --oneline # shows the last 5 commits. Find the last commit before the maven prepare one.
  • git reset --hard hash-of-commit where hash-of-commit is from the log
  • git push -f origin branch-name # force needed because removing history

Remove the previously created tag

Next, because the release:prepare created a tag, you need to remove it. Do this:

  • git tag to list the tags
  • git tag -d name-of-tag to delete, e.g. uimaj-3.1.1. This deletes it locally only.
  • git push origin :refs/tags/name-of-tag to remove the tag in the remote.

Do any fixes, updates and then rerun the release