Preparing a PROJ Release =============================================================================== Preparing a PROJ release is a three-step process. Before the actual release is published we want to issue one or more release candidates to ensure that the code is in fact ready to be released. That is step one. Step two starts when a release candidate has been selected for promotion to final release. Step three updates version numbers in the master branch to avoid confusion between released code and code still in development. The three phases are described below. 1 Release candidate =============================================================================== At least one release candidate is necessary before the final release is published. In case more than one release candidate is needed most steps below can be skipped depending on what prompted the release candidate 1+n. Steps 1.6 and 1.7 are mandatory for all release candidates, otherwise it will in most cases only be necessary to update the NEWS section (1.3). Release candidates should be released about a week before the final release is scheduled. When preparing major version releases it may be wise to issue the release candidate earlier than that. When a release candidate has not prompted any request for changes in 48 hours, a motion for promotion to final release should be issued on the PROJ mailing list. The PROJ PSC guidelines describes the rules for passing a motion. 1.1 Update ABI version numbers: ------------------------------------------------------------------------------- In case of a un-planned maintenance release, make sure that version numbers are propertly updated: see 3.1 Determine the ABI version number. It consists of "current:revision:age". Follow the steps below to determine the next ABI version number: - If the library source code has changed at all since the last update, then increment revision (c:r:a becomes c:r+1:a). - If any interfaces have been added, removed, or changed since the last update, increment current, and set revision to 0. - If any interfaces have been added since the last public release, then increment age. - If any interfaces have been removed since the last public release, then set age to 0. Update the following files with the new ABI version number: - `src/Makefile.am` Update -version-info - `CMakeLists.txt`: Update PROJ_BUILD_VERSION (cur:rev:age) and PROJ_API_VERSION (current) *Commit the changes to master.* 1.2 Update man pages ------------------------------------------------------------------------------- Man pages are (mostly) automatically generated from the Sphinx docs. Follow these steps: - Temporarily update `version` and `data_version` in `docs/source/conf.py` - run `scripts/update_man.sh` - Revert version number in `docs/source/conf.py` The `update_man.sh` script builds the man pages and commits the update man pages to master. 1.3 Write release notes ------------------------------------------------------------------------------- Update `NEWS` with descriptions of the changes since the last release. Hopefully issues and pull requests that go into the new release have been properly tagged with the milestone for the current release. End the section by thanking the authors that contributed to the release. Get a sorted list of contributors in descending order of activity: ``` git shortlog -sn x.y.z..HEAD | tac | awk '{$1=""; print $0}' ``` where `x.y.z` is the tag of the previous release. You may need to edit the list slightly since not all authors has properly configured their names in git. *Commit the changes to master.* 1.4 Update `CITATION` ------------------------------------------------------------------------------- If needed, update the year in `CITATION`. *Commit the changes to master.* 1.5 Create maintenance branch ------------------------------------------------------------------------------- *Skip this step if you are preparing a patch release or RC2 and later.* Create the branch: ``` git branch x.y ``` where `x` is the major version number and `y` is the minor version number. Bug fixes found in the release candidates should be pushed to master and subsequently cherry-picked to the maintenance branch. *Push branch upstream.* 1.6 Prepare and upload archives ------------------------------------------------------------------------------- Run autoconf and configure the build: ``` ./autogen.sh mkdir build cd build ../configure make dist ``` Rename the archives and generate MD5 sum files: ``` mv proj-x.y.z.tar.gz proj-x.y.zRCn.tar.gz mv proj-x.y.z.zip proj-x.y.zRCn.zip md5 proj-x.y.zRCn.tar.gz > proj-x.y.zRCn.tar.gz.md5 md5 proj-x.y.zRCn.zip > proj-x.y.zRCn.zip.md5 ``` Upload to the OSGeo download server: ``` scp proj-x.y.zRCn.* warmerdam@download.osgeo.org:/osgeo/download/proj ``` Adjust version numbers and usernames accordingly. 1.7 Announce the release candidate ------------------------------------------------------------------------------- Announce the release candidate on the PROJ mailing list. 1.8 Promotion to final release ------------------------------------------------------------------------------- When you are confident that the latest release candidate is ready for promotion to final release a motion for promotion should be issued on the PROJ mailing list. Allow for a minimum of 48 hours for voting time. 2 Final release =============================================================================== Barring a successful promotion process we can proceed with the final release. 2.1 Prepare and upload archives ------------------------------------------------------------------------------- See step 1.6 above. Do not rename the archives with RC postfixes. 2.2 Update website ------------------------------------------------------------------------------ - Add the release notes from `NEWS` to `docs/source/news.rst` These vim substitutions are helpfull when converting NEWS to rst: :!(\#(\d\{4}\))!(`\#\1 `_)! :s/^o/*/ - Update download links in `docs/source/download.rst` - Update `$TRAVIS_BRANCH` in `travis\after_success.sh` to new maintenance branch. *Commit the changes to master and cherry-pick into maintenance branch.* When pushed upstream the website will be update to the current version. 2.3 Tag the release ------------------------------------------------------------------------------- Tag the release with: ``` git tag -a -m "Create tag x.y.z" x.y.z git push --tags ``` 2.4 Prepare the release on GitHub ------------------------------------------------------------------------------- When the new tag is pushed upstream GitHub picks up that a new release has been issued. Update the new release on https://github.com/OSGeo/PROJ/releases with the release notes from `NEWS` and add the prepared source distribution archives to the release (otherwise GitHub will just package the entire repository - we don't want that). 2.5 Announce the new release ------------------------------------------------------------------------------- The release should be announced on PROJ and MetaCRS mailing lists. Additionally the release announcement should be sent to news_item@osgeo.org which will add the announcement to osgeo.org and other OSGeo communication channels. Make some noise on Twitter and other relevant social media. 3 Post final release =============================================================================== 3.1 Update version numbers ------------------------------------------------------------------------------- PROJ uses [semantic versioning](http://semver.org/). Depending on the changes in the release will be either a major, minor or patch release. Update the version numbers in the files. - configure.ac: Update the version number in AC_INIT(). - src/proj.h: Update PROJ_VERSION_MAJOR, PROJ_VERSION_MINOR and PROJ_VERSION_PATCH. - src/proj_api.h: Update PJ_VERSION. - src/release.cpp: Update date to the scheduled release date. - CMakeLists.txt: Update proj_version() - docs/source/conf.py: Update version number *Commit changes. Either to master or maintenance branch depending on the nature of the release.* 3.2 Disable website deployment when releasing a new non-bugfix version ------------------------------------------------------------------------------- If the previous active version was, let's say, 6.1 and the new version is, let's say, 6.2, then checkout 6.1 branch, and in travis/after_success.sh, remove the code that causes commits to 6.1 to cause a website refresh, that is remove the code under `if test "$TRAVIS_SECURE_ENV_VARS" = "true" -a "$TRAVIS_BRANCH" = "6.1"; then`. Also edit docs/source/conf.py to change the active branch for documentation in the `github_version` variable.