-
Notifications
You must be signed in to change notification settings - Fork 2.2k
How to Create a Release
Creating a POCO release is quite simple, thanks to a few scripts. Generally, the following steps have to be performed in order to create a release. In the following we assume that the release is being created from the GitHub develop branch.
You'll need to update both the CHANGELOG file (in the repository root directory) and the Release Notes documentation page in doc/99100-ReleaseNotes.page. Please follow the format used in the respective file. Generally, you can simply copy over the items from CHANGELOG into the Release Notes page (take care of proper indentation!), but make sure that any class and method names in the Release Notes are fully qualified, so that the documentation generator can create proper links. Also, add a "Incompatible Changes and Possible Transition Issues" section if there are any changes that break backwards compatibility or otherwise require attention. While you're at it, also update the platform notes (99150-WindowsPlatformNotes.page, etc.), Acknowledgements and CONTRIBUTORS if necessary.
Update the VERSION file (also in the repository root directory) with the correct version number (e.g., 1.5.1). This file will be used by the release script. Also, update the DLLVersion.rc resource file for Windows DLL builds and the libversion file (shared library version number). While at it, make sure that Poco/Version.h also has the correct version number.
The release script is called mkrel and is located in the $POCO_BASE/release/script directory. Before running the script, make sure that the POCO_BASE environment variable is set and that the PATH environment variable incudes $POCO_BASE/release/script, e.g.:
export POCO_BASE=`pwd`
export PATH=$POCO_BASE/release/script:$PATH
Since we have packages for Windows (using CRLF line endings) and Unix(-like) platforms (LF line endings), the release must be built twice. On Windows, the release script has to be run under Cygwin. So in order to build all files required for a release, you'll have to run the release script 4 times. Twice on Windows (Cygwin) and twice on OS X or Linux.
We currently have two release packages, the Basic Edition containing only Foundation, XML, Util and Net, and the Complete Edition containing Data, Crypto, NetSSL, Zip and Page Compiler in addition to the core libraries. Therefore, you must run the release script twice on each platform (Windows and OS X/Linux). For the Basic Edition, simply run the release script without arguments:
mkrel
For the Complete Edition, run the release script with the "all" argument.
mkrel all
Note that the argument to mkrel actually refers to a release specification file located in $POCO_BASE/release/spec. For the Complete Edition, the specification file is $POCO_BASE/release/spec/all.release.
The release packages will be placed in $POCO_BASE/releases. Package names include version numbers and edition designation. Examples:
$POCO_BASE/releases/poco-1.5.1.tar.gz
$POCO_BASE/releases/poco-1.5.1.tar.bz2
$POCO_BASE/releases/poco-1.5.1.zip
$POCO_BASE/releases/poco-1.5.1-all.tar.gz
$POCO_BASE/releases/poco-1.5.1-all.tar.bz2
$POCO_BASE/releases/poco-1.5.1-all.zip
Note that the Zip files must be taken from a Cygwin build. In the GitHub downloads repository, create a new folder for the release (poco-1.5.1) and copy these files to that folder.
For building the documentation, another script (located in $POCO_BASE/release/script) called mkdoc is available. We only build the documentation for the Complete Edition, so simply run:
mkdoc all
to build the documentation package. The script should be run on OS X or Linux (it may work under Cygwin as well, but this has not been tested). The script will first build the PocoDoc tool and then run it to generate the HTML reference documentation. The result will be packed into .tar.gz and .zip archives and placed in $POCO_BASE/releases:
$POCO_BASE/releases/poco-1.5.1-all-doc.tar.gz
$POCO_BASE/releases/poco-1.5.1-all-doc.zip
Copy these two files to the GitHub downloads repository as well.
Update the website with proper download links for the new release and add announcements for the release. Currently this has to be done by Applied Informatics.
Merge the release changes into the master branch (either from the develop branch, or a release-specific branch) and create a new tag (poco-1.5.1) for the release.
In most cases, you can simply merge the develop branch into the master branch, e.g.:
git checkout master
git merge develop
git push origin master
The release should be tagged on the master branch:
git tag -a poco-1.5.1-release -m 'Release 1.5.1'
git push origin master --tags