-
Notifications
You must be signed in to change notification settings - Fork 80
Release Guide
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.
- Prerequisites
- Create a Branch for the Release
- Documentation Updates
- Tagging the Release
- LocationTech Build Jobs
- GeoGig Plugin Builds
- Update the GeoGig Web Page
- GitHub Release
- Notify Dev Mailing List
In order to complete the release, you will need:
- committer access to the LocationTech GitHub GeoGig repository
- access to the LocationTech Jenkins build server
You should be able to obtain both by following the Contributor Guide.
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 [email protected]: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.
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.
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.
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.
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 <[email protected]>
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.
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.
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.
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.
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).
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).
First, clone the Boundless GeoGig plugins repository:
$ git clone [email protected]:boundlessgeo/geogig-plugins.git
$ cd geogig-plugins
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>
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.
If you don't already have a GeoServer clone, cone it:
$ git clone [email protected]:geoserver/geoserver.git
$ cd geoserver
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
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>
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.
Now, you need to generate all the updated HTML pages for http://geogig.org and publish them.
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.
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 — 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
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:
On the Release Draft page, fill in:
- The tag you created (example:
v1.1.1
) - The Release Title (example:
GeoGig Release 1.1.1
) - The Release notes (you can usually copy content you edited here, and follow the formatting of pervious releases)
- Upload the plugin bundles (The OSM and GeoServer plugins you built here)
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.