257 строки
8.8 KiB
Plaintext
257 строки
8.8 KiB
Plaintext
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 <https://github.com/OSGeo/issues/\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.
|