| Title: Release Guide |
| |
| This page describes the steps that a Cayenne Release Manager needs to |
| perform to prepare a release. The specifics of Cayenne release process is |
| that we are publishing both downloadable assemblies and Maven artifacts, so |
| we have to build and publish things twice. Both forms of Cayenne release |
| are also available for evaluation during the vote. |
| |
| ## Prerequisites |
| |
| * A release manager must have his public key appended to the KEYS file |
| checked in to source control and the key published on one of the public key servers. |
| More info can be found at [http://www.apache.org/dev/release-signing.html](http://www.apache.org/dev/release-signing.html) |
| * Make sure "apache-releases" repository is configured in |
| *~/.m2/settings.xml* and an appropriate password is setup. See [this page](http://www.apache.org/dev/publishing-maven-artifacts.html) |
| for details. |
| * As Cayenne has modules which require Java 1.8, you should use Java 1.8 to perform the release. |
| |
| ## Preparing Sources |
| |
| * Edit UPGRADE-NOTES.txt if there is anything to add there. |
| * Check Sources Compliance with [RAT](http://creadur.apache.org/rat/). To run RAT, |
| download the distro and unpack it somewhere. You can run it directly, or use a convenience script available at the root of Cayenne |
| source. Then read the report and fix any issues. |
| |
| cd cayenne |
| ./rat.sh ~/Desktop/apache-rat-0.9/apache-rat-0.9.jar > report.txt |
| |
| ## Tagging the Repo and Releasing Maven Artifacts |
| |
| |
| * Create a Git tag and Create Maven Staging Repository: |
| |
| cd cayenne |
| mvn release:clean |
| mvn release:prepare -DpreparationGoals="clean install" -DautoVersionSubmodules=true |
| mvn release:perform -P gpg [-Dgpg.keyname=B8AF90BF] |
| |
| * Close the staging repo. Login to [https://repository.apache.org/](https://repository.apache.org/) with |
| Apache ID/password, go to "Staging Repositories" page. Select a staging |
| repository that was just created during "*mvn release:perform*", click |
| "Close". Take a note of the freshly created staging repository URL. It will |
| be used by the people voting on Cayenne. It may look like this: |
| [https://repository.apache.org/content/repositories/orgapachecayenne-052/](https://repository.apache.org/content/repositories/orgapachecayenne-052/) |
| |
| ## Releasing Downloadable Assemblies |
| |
| * Switch to the release tag created above. |
| |
| * Build source package (it will be the basis for the binary packages built |
| in the next steps) : |
| |
| mvn clean install -Passembly,src |
| |
| * Build binary assemblies. Take *"assembly/target/cayenne-XXX-src.tar.gz"*, unpack it somewhere, and |
| perform binary builds from the unpacked directory (NOT FROM GIT CHECKOUT). _Release manager may skip |
| running unit tests from here, as shown |
| below, although release evaluators should use the src assembly for [unit testing](running-unit-tests.html) |
| and other kinds of testing._ |
| |
| mvn clean install -Passembly,generic -Dmaven.test.skip=true |
| |
| # You will need to do this on OS X, and use at least Java 1.8 |
| mvn clean install -Passembly,mac -Dmaven.test.skip=true |
| |
| # You will need to do this on Windows |
| mvn clean install -Passembly,windows -Dmaven.test.skip=true |
| |
| For further details on a general Cayenne build process check [this page](building-cayenne.html). |
| |
| * Signing assemblies |
| |
| For more info visit [this page](http://www.apache.org/dev/release-signing.html) |
| . Release manager key must be in the project KEYS file. Signing is a manual |
| procedure not included in the Ant or Maven script. Here is how it might |
| work ("-u" option can be omitted if you have only one GPG key): |
| |
| gpg -a -b -u B8AF90BF cayenne-X.X.tar.gz |
| gpg --print-md MD5 cayenne-X.X.tar.gz > cayenne-X.X.tar.gz.md5 |
| |
| * Assemblies, signature and checksum files are committed to the special SVN repo |
| used for staging development releases: [https://dist.apache.org/repos/dist/dev/cayenne/](https://dist.apache.org/repos/dist/dev/cayenne/). Use a separate folder for each release. For more info on this repository check [the infrastructure docs](http://apache.org/dev/release.html#upload-ci). |
| |
| |
| |
| ## Voting |
| |
| * The vote is started on the dev mailing list. |
| * All committers are encouraged to vote on releases. Committer votes will |
| be considered by the PMC (particularly -1 votes will be discussed) when |
| making the final decision, but are not binding. |
| * Each PMC member will do the following before voting on a release: |
| a. download the artifacts |
| b. satisfy themselves that the source matches the appropriate svn tag. |
| This can be done by diffing the source against a recent svn checkout. |
| c. satisfy themselves that the Apache licensing requirements are met (this |
| will usually be achieved by ensuring that all notices are in place and |
| verifying that the source matches SVN since all commits to SVN are possible |
| only if the committer has a CLA on file). |
| d. satisfy themselves that the binary distribution is sane and passes |
| basic usability tests. For example, that the Cayenne modeler runs and the |
| main jar passes some basic tests. |
| e. satisfy themselves that the source passes agreed unit tests (either by |
| running them manually or verifying that Hudson has run those tests against |
| the equivalent source). |
| |
| |
| ## Publishing the Release |
| |
| * Publish Maven artifacts. Go back to [https://repository.apache.org/](https://repository.apache.org/), |
| select the staging repo and click "Release". |
| |
| * Publish downloadable assemblies by moving them to the release repo: |
| |
| $ svn mv https://dist.apache.org/repos/dist/dev/cayenne/X.X \ |
| https://dist.apache.org/repos/dist/release/cayenne/ |
| |
| |
| ## After the release |
| |
| * Delete a previous version of Cayenne release of the same branch from the dist server. |
| It should be already [archived by Apache] (http://www.apache.org/dev/release.html#when-to-archive). Do this with an svn command like this: |
| |
| $ svn rm https://dist.apache.org/repos/dist/release/cayenne/Y.Y |
| |
| * [Tell Jira](https://issues.apache.org/jira/plugins/servlet/project-config/CAY/versions) |
| that the release has been released. Ensure there is another milestone or |
| release target already created for further work, but this was probably |
| already done when a branch was created in preparation for release. |
| * Update the [DOAP file](http://svn.apache.org/repos/asf/cayenne/site/cms/trunk/content/doap/cayenne.rdf) |
| which will update |
| http://projects.apache.org/projects/cayenne.html automatically. |
| * If the release is significant, consider press releases to relevant news |
| sources |
| * Review the main website pages (front page and why-cayenne especially) to |
| add any new features |
| * Add a news item to the Cayenne web site |
| * Send an email to the Cayenne user and developer lists |
| * Send a notification email to announceATapache.org |
| * Update [http://en.wikipedia.org/wiki/Apache_Cayenne](http://en.wikipedia.org/wiki/Apache_Cayenne) |
| |
| ## Reference: |
| |
| * Apache release publishing: |
| [http://www.apache.org/dev/release-publishing.html](http://www.apache.org/dev/release-publishing.html) |
| * Apache Maven release publishing: |
| [http://www.apache.org/dev/publishing-maven-artifacts.html](http://www.apache.org/dev/publishing-maven-artifacts.html) |
| * ARAT: [http://code.google.com/p/arat/](http://code.google.com/p/arat/) |
| * Signing Releases: [http://www.apache.org/dev/release-signing.html](http://www.apache.org/dev/release-signing.html) |