Skip to content

Release Guide

Jump to bottom Edit New page
Erik Merkle edited this page Jul 6, 2017 · 2 revisions

Overview

For each GeoGig version release (alphas, betas, Release Candidates and Final Releases), a process has to be followed to properly publish release artifacts and documentation. It is assumed that all code and tests are building and passing and the content for the release is ready to go.

Table of Contents

  1. Prerequisites
  2. Create a Branch for the Release
  3. Documentation Updates
  4. Tagging the Release
  5. LocationTech Build Jobs
  6. GeoGig Plugin Builds
  7. Update the GeoGig Web Page
  8. GitHub Release
  9. Notify Dev Mailing List

Prerequisites

In order to complete the release, you will need:

You should be able to obtain both by following the Contributor Guide.

Create a Branch for the Release

Once you are ready to create the release, it is best to make all changes required to cut the release in a Release branch. If you haven't already, clone the GeoGig repository:

$ git clone git@github.com:locationtech/geogig.git
$ cd geogig

Create a release branch:

$ git checkout -b r1.1.1 -t origin/master

This branch is local to your workspace until you push it to the remote later on.

Documentation Updates

For each release, the Release Notes and the README should be updated. If the release does not contain any additions, deletions or modifications to external APIs or commands, then updates to the Release Notes and README may be all that's needed.

If there are changes in either the APIs or commands, then the appropriate RST documents in the doc folders should be updated as well. Changes to the doc folder should be made as part of a commit that changes the functionality, but the documentation in this folder should be reviewed prior to every release to ensure consistency.

Make all the documentation changes needed and commit them to your local release branch you created above.

Tagging the Release

Edit the GeoGig POMs

Once all the documents have been updated in your release branch, you need to update the POM version numbers to the release version you wish to create. This should be done in a single commit, with no other changes, as it will need to be reverted. Currently, the list of POMs that have to be edited are:

./src/datastore/pom.xml
./src/geotools/pom.xml
./src/parent/pom.xml
./src/ql/pom.xml
./src/gui/pom.xml
./src/cli-app/pom.xml
./src/web/functional/pom.xml
./src/web/app/pom.xml
./src/web/api/pom.xml
./src/web/pom.xml
./src/storage/rocksdb/pom.xml
./src/storage/postgres/pom.xml
./src/storage/pom.xml
./src/core/pom.xml
./src/cli/pom.xml
./src/api/pom.xml

In each POM, there is either a parent section, a version section, or both that needs to be modified. A parent section looks like this:

  <parent>
    <groupId>org.locationtech.geogig</groupId>
    <artifactId>geogig</artifactId>
    <version>1.1-SNAPSHOT</version>
    <relativePath>../parent/pom.xml</relativePath>
  </parent>

A version section looks like this:

  <artifactId>web</artifactId>
  <version>1.1-SNAPSHOT</version>
  <packaging>pom</packaging>
  <name>Web modules</name>

For each POM, you need to edit the <version> element value to be the release version you want. For example, if we are cutting a 1.1.1 version, we would update the above sections to look like:

  <parent>
    <groupId>org.locationtech.geogig</groupId>
    <artifactId>geogig</artifactId>
    <version>1.1.1</version>
    <relativePath>../parent/pom.xml</relativePath>
  </parent>

and

  <artifactId>web</artifactId>
  <version>1.1.1</version>
  <packaging>pom</packaging>
  <name>Web modules</name>

Again, make the POM changes all in a single commit, separate from the documentation changes. This is because the official LocationTech build jobs will only build release versions once. That needs to happen via a release tag.

Create the Release Tag

Once you have made the POM changes above, you need to tag the commit with an annotated Git tag. Before creating a tag, you need to make sure you have a GPG key setup in GitHub so you can sign and verify tags. Follow this to setup a new GPG signature with GitHub if you haven't already.

Once you have GPG setup, create the release tag:

$ git tag -s -a v1.1.1 -m "tag for Release version 1.1.1"

That should create an annotated tag (v1.1.1) with the commit message (tag for Release version 1.1.1) and sign the tag (-s). The tag will now be pinned to the commit you made setting the versions in the pom above.

Revert the POM Versions

After creating the tag, you need to revert the commit that you made to set the release versions in the POMs. Again, this is required because the LocationTech Jenkins build jobs will build and deploy GeoGig artifacts as soon as a commit hits the repository. If a commits are pushed where the POM versions are not a SNAPSHOT version (i.e. 1.1.1 for example), the build job will build and deploy the RELEASE version artifacts and we will not be able to remove or replace them. This will cause the Jenkins Release jobs to fail, since they will try to re-deploy the Release version from the tag you just created.

To revert the last commit, get the commit hash from the log:

$ git log

will show the commits. Grab the hash:

commit bb35fccca5d88aab5c69328eedef42af07fed2f2
Author: GeoGig <geogig@geogig.org>
Date:   Wed May 10 17:03:27 2017 -0500

    Update POMs to Release v1.1.1

and revert:

$ git revert bb35fccca5d88aab5c69328eedef42af07fed2f2

This will revert the POM versions back to (in this case) 1.1-SNAPSHOT, but still leave the commit that set the versions to 1.1.1 and the tag that points to that commit.

LocationTech Build Jobs

Once the docs are updated, and the release tag is created, and the POM versions are reverted, it's time to push the release branch up and merge it into the appropriate upstream branch. In the examples above, we are trying to release version 1.1.1 from the 1.1.x upstream branch. We can use the same process to cut a release from the upstream master branch if desired.

LocationTech has a Jenkis Continuous Integration build server here. Currently, there is a build job that builds the master branch, another that builds the 1.1.x branch, and two more that are responsible for building and deploying Release versions. The way the jobs are designed, only SNAPSHOT versions should be built on the master and 1.1.x branches, and RELEASE versions should be built from tags.

Push the Release Branch

To get the release docs in, either push the r1.1.1 branch up and create a pull request on GitHub to pull the changes into the 1.1.x branch:

$ git push origin r1.1.1

(after this, log in to GitHub and create a pull request from the r1.1.1 branch into the 1.1.x branch and merge the PR)

or push the commits from the r1.1.1 release branch directly to the 1.1.x branch:

$ git push origin 1.1.x

Once the changed have been merged, the build job here should kick off. Once that job completes, if there are no failures or issues, you need to now edit the Release jobs on Jenkins to be ready to build the tag you created.

Edit the Release Build Jobs

Log in to the LocationTech Jenkins build server, if you haven't already, here. Navigate to the geogig-release job configuration and scroll down to the Source Code Management section. In this section, edit the Branches to build area so that the Branch Specifier is set to the release tag, v1.1.1 from the above examples. Scroll down to the bottom of the configuration page and click Save.

While still logged in, navigate to the geogig-release-deploy job configuration and do the same as above. Scroll to the Source Code Management section and edit the Branch Specifier so it is set to the release tag, v1.1.1. Save the configuration.

Push the Release Tag

Once you have updated the Release build jobs to look for the new tag, it's time to push the tag. In Git, tags are pushed separately from branches (usually), so you will need to push the tag you created earlier:

$ git push origin v1.1.1

Once the tag is pushed, you can now trigger the build and deploy jobs for the release. Log back into Jenkins (if you are not currently logged in) and build geogig-release by clicking the Build Now button. Once this job finishes (and builds successfully), run the geogig-release-deploy build by clicking its Build Now button. Completing this build will deploy the official release artifacts (1.1.1 in this example).

GeoGig Plugin Builds

When the geogig-release-deploy job completes, it's now time to build the plugins for GeoGig. Currently, there are only two plugins, the Open Street Map plugin and the GeoServer plugin. The GeoServer plugin needs to be built against all supported versions of GeoServer (currently 2.11, 2.10 and 2.9).

Open Street Map Plugin

Clone the Plugins Repository

First, clone the Boundless GeoGig plugins repository:

$ git clone git@github.com:boundlessgeo/geogig-plugins.git
$ cd geogig-plugins

Edit the Plugin POMs

Next, edit the POMs to use the release version (similar to how the POMs in GeoGig were edited). In geogig-plugins/src/parent/pom.xml edit the <version> element so the value matches the GeoGig release version:

  <parent>
    <groupId>org.locationtech.geogig</groupId>
    <artifactId>geogig</artifactId>
    <version>1.1-SNAPSHOT</version>
  </parent>

should become

  <parent>
    <groupId>org.locationtech.geogig</groupId>
    <artifactId>geogig</artifactId>
    <version>1.1.1</version>
  </parent>

Again, edit geogig-plugins/src/osm/pom.xml so that the <version> element value matches the release:

  <parent>
    <groupId>org.geogig</groupId>
    <artifactId>geogig-plugins</artifactId>
    <version>1.1-SNAPSHOT</version>
    <relativePath>../parent/pom.xml</relativePath>
  </parent>

should become

    <groupId>org.geogig</groupId>
    <artifactId>geogig-plugins</artifactId>
    <version>1.1.1</version>
    <relativePath>../parent/pom.xml</relativePath>
  </parent>

Build the OSM Plugin

Now you can build the plugin. Assuming you still have a terminal open and are in the geogig-plugins repository directory:

$ cd src/parent
$ mvn clean install -DskipTests assembly:single

This will build the OSM plugin bundle, relative to your geogig-plugins directory:

src/osm/target/geogig-plugins-osm-1.1.1.zip

NOTE: Save this bundle as you will need to upload it to GitHub in the next section.

GeoServer Plugins

Clone the GeoServer Repository

If you don't already have a GeoServer clone, cone it:

$ git clone git@github.com:geoserver/geoserver.git
$ cd geoserver

Checkout the GeoServer Branch

You will need to repeat the next steps multiple times, once for each version of GeoServer that GeoGig supports.

NOTE: At the end of each plugin build, you will need to copy the plugin to a safe location as the build process will remove any previously built plugins.

$ git checkout 2.11.x

Edit the GeoGig POM

You need to edit the POM, similarly as before. Relative to the geoserver repository checkout, you need to make the properties section of src/community/geogig/pom.xml change from this:

  <properties>
    <geogig.version>1.1-SNAPSHOT</geogig.version>

to this

  <properties>
    <geogig.version>1.1.1</geogig.version>

Build the GeoServer Plugin

Now you can build the plugin. Unfortunately, the way the GeoServer community modules are setup, you have to build them all to get the GeoGig plugin built correctly. Assuming you still have a terminal open and are in the geoserver repository directory:

$ mvn clean install -DskipTests -f src/community/pom.xml -P communityRelease assembly:attached

This will build all the community modules. When finished, you should have a GeoServer plugin bundle here:

src/community/target/release/geoserver-2.11-SNAPSHOT-geogig-plugin.zip

NOTE: Save the ZIP bundle somewhere safe. You will need to upload it to GitHub in the next section.

Once you have saved the plugin bundle, repeat the Checkout, Edit, and Build secitons, changing 2.11 for each GeoServer version supported (i.e. 2.10.x for 2.10 and 2.9.x for 2.9) and saving the plugin builds after each process.

Update the GeoGig Web Page

Now, you need to generate all the updated HTML pages for http://geogig.org and publish them.

Generate Updated HTML

Open a terminal to your geogig repository directory and ensure you have your release branch checked out:

$ git checkout r1.1.1

change to the doc directory

$ cd doc

For each of the documentation sub-directories (manual, manpages, technical, upgrade, and workshops), edit the relative source/conf.py file so the release and version values match the Release you are cutting. Example:

# The short X.Y version.
version = '1.1'
# The full version, including alpha/beta/rc tags.
release = '1.1.1'

Now, build all the HTML pages:

$ ./build_all.sh

The build_all.sh will build all the HTML pages based on the RST documentation updated in Documentation Updates.

Copy HTML Pages and Push

Next, checkout the gh-pages branch:

$ git checkout gh-pages

Copy all the HTML pages over:

$ cd docs
$ cp -R ../doc/manual/build/html/* .
$ cd ../manpages
$ cp -R ../doc/manpages/build/html/* .
$ cd ../technical
$ cp -R ../doc/technical/build/html/* .
$ cd ../workshop
$ cp -R ../doc/workshops/build/html/* .
$ cd ../upgrade
$ cp -R ../doc/upgrade/build/html/* .
$ cd ..

Edit the index.html page to set the Release version as well. It's in a few places, so make sure you get them all:

  <title>GeoGig User Manual &mdash; GeoGig 1.1.1 User Manual</title>

        VERSION:     '1.1.1',

      <link rel="top" title="GeoGig 1.1.1 User Manual" href="#" />

  <li>GeoGig 1.1.1 User Manual</li>

Add all the changes, commit and push:

$ git add .
$ git commit -s -m "Update docs for Release 1.1.1"
$ git push origin gh-pages

Once you push the gh-pages branch, the updated HTML content should be almost immediately available at http://geogig.org

GitHub Release

Once all the plugins have been built, it's time to create the Release on GitHub. Navigate to the GeoGig Release page and click the Draft a new release button at the top right:

release page

On the Release Draft page, fill in:

  1. The tag you created (example: v1.1.1)
  2. The Release Title (example: GeoGig Release 1.1.1)
  3. The Release notes (you can usually copy content you edited here, and follow the formatting of pervious releases)
  4. Upload the plugin bundles (The OSM and GeoServer plugins you built here)

release draft

Notify Dev Mailing List

Lastly, once everything is built, pushed and ready to go, you need to inform the communities of interest. At the very least, send an email to the GeoGig developer mailing list. You can use most of the RELEASE_NOTES in the body of the email, or follow an example from previous releases.

You may also want to notify other communities of interest at this time.

Add a custom footer
Add a custom sidebar
Clone this wiki locally