| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| <document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| |
| <properties> |
| <title>Release Process</title> |
| <author email="syncope-dev@incubator.apache.org">Apache Syncope Documentation Team</author> |
| </properties> |
| |
| <body> |
| <div class="toc_container"> |
| <macro name="toc"> |
| <param name="class" value="toc"/> |
| </macro> |
| </div> |
| |
| <section name="Introduction"> |
| <p>The Syncope team is using the |
| <a href="http://repository.apache.org">Apache Nexus repository</a> for releasing SNAPSHOT and release artifacts. |
| More details on releasing artifacts and using Nexus can be found on the Maven website at |
| <a href="http://maven.apache.org/developers/release/apache-release.html">http://maven.apache.org/developers/release/apache-release.html</a>. |
| </p> |
| </section> |
| |
| <section name="Prerequisites"> |
| <subsection name="GPG"> |
| Install/Configure |
| <code>GPG</code> - The artifacts that are deployed to the ASF central repository need to |
| be signed. To do this you will need to have a public and private keypair. There is a very good |
| <a href="http://www.sonatype.com/people/2010/01/how-to-generate-pgp-signatures-with-maven/">guide</a> that |
| will walk you though this. |
| </subsection> |
| |
| <subsection name="Apache Maven"> |
| <p>Install Apache Maven 3.0.3 or higher; we strongly |
| encourage our committers to install |
| <a href="http://maven.apache.org/download.html">Apache Maven 3.0.4</a>. |
| </p> |
| |
| <p>As of Maven 2.1.0 you can now encrypt your servers passwords. We highly recommend that you follow this |
| <a href="http://maven.apache.org/guides/mini/guide-encryption.html">guide</a> to set your master password and |
| use it to encrypt your ASF password in the next section. |
| </p> |
| </subsection> |
| |
| <subsection name="ASF settings"> |
| <p>Using the instructions from the previous step encrypt your Sonatype password and add the following servers to |
| your |
| <code>~/.m2/settings.xml</code> file. You may already have other servers in this file. If not just create |
| the file. |
| </p> |
| |
| <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?> |
| <settings> |
| ... |
| <servers> |
| <server> |
| <id>apache.snapshots.https</id> |
| <username>{put your ASF username here}</username> |
| <password>{put your encrypted password here}</password> |
| </server> |
| <server> |
| <id>apache.releases.https</id> |
| <username>{put your ASF username here}</username> |
| <password>{put your encrypted password here}</password> |
| </server> |
| </servers> |
| ... |
| <profiles> |
| <profile> |
| <id>apache</id> |
| <activation> |
| <activeByDefault>false</activeByDefault> |
| </activation> |
| <properties> |
| <mavenExecutorId>forked-path</mavenExecutorId> |
| <gpg.keyname>your-gpg-keyname</gpg.keyname>\ |
| <!-- optional --> |
| <gpg.passphrase>your-gpg-passphrase</gpg.passphrase> |
| </properties> |
| </profile> |
| </profiles> |
| ... |
| </settings>]]></source> |
| </subsection> |
| </section> |
| |
| <section name="Release steps"> |
| |
| <subsection name="Prepare the source for release"> |
| <ol> |
| <li>Clean up JIRA so the |
| <b>Fix Version</b> in issues resolved since the last |
| release includes this release version correctly. Also, transition any |
| <b>Resolved</b> issues to the |
| <b>Closed</b> state. |
| </li> |
| <li> |
| Update the <tt>CHANGES</tt> file in a working copy of the project root based on the Text release reports |
| from JIRA. |
| </li> |
| <li> |
| Update the |
| <a href="downloads.html">downloads</a> site page by adding the new release artifacts with base |
| URL |
| <source>http://www.apache.org/dyn/closer.cgi/incubator/syncope/<version>/</source> |
| </li> |
| <li> |
| Commit any changes back to svn: |
| <source>svn commit -m "updating files for release"</source> |
| </li> |
| <li> |
| Perform a full build and deploy the SNAPSHOT artifacts: |
| <source>mvn -P all clean deploy</source> |
| </li> |
| </ol> |
| </subsection> |
| |
| <subsection name="Get source tree"> |
| <ol> |
| <li> |
| <strong> |
| <em>Only for new major releases (like 1.0.0 to 1.1.0):</em> |
| </strong> |
| <br/> |
| Create a sub-branch from which to make the release. |
| <br/> |
| Releasing from a branch will allow any cosmetic changes that need to be made for the release to be |
| approved to be done without preventing other more disruptive advances in the trunk from potentially |
| causing problems with the release. It also provides a future maintenance branch (like 1.0.x.) |
| <br/> |
| A branch can be made by running: |
| <source>mvn -P apache-release release:branch -DbranchName=1.0.x</source> |
| </li> |
| <li> |
| Checkout a clean copy of the trunk/branch to release using command line svn: |
| <source>svn checkout https://svn.apache.org/repos/asf/incubator/syncope/trunk/ release</source> |
| </li> |
| </ol> |
| </subsection> |
| |
| <subsection name="Prepare the release"> |
| <ol> |
| <li> |
| Do a dry run of the |
| <tt>release:prepare</tt> step. |
| <source>mvn -P apache-release release:prepare -DdryRun=true</source> |
| |
| The dry run will not commit any changes back to SVN and gives you the opportunity to verify that the |
| release process will complete as expected. |
| |
| <p> |
| <em>If you cancel a |
| <tt>release:prepare</tt> before it updates the pom.xml versions, then use the |
| <tt>release:clean</tt> goal to just remove the extra files that were created. |
| </em> |
| </p> |
| </li> |
| <li> |
| Verify that the release process completed as expected: |
| <ol> |
| <li>The release plugin will create |
| <code>pom.xml.tag</code> files which contain the |
| changes that would have been committed to SVN. The only differences between |
| <code>pom.xml.tag</code> and its corresponding |
| <code>pom.xml</code> file should be the version |
| number. |
| </li> |
| <li> |
| If other formatting changes have been made you should review the changes and then commit them: |
| <source>svn commit -m "fixing formatting for release"</source> |
| </li> |
| <li> |
| Assuming the |
| <code>.tag</code> files look OK you may proceed and do any other validation you feel necessary. |
| The following list may be helpful: |
| <ol> |
| <li>Check |
| <tt>release.properties</tt> and make sure that the scm properties have the |
| right version. Sometimes the scm location can be the previous version not the next version. |
| </li> |
| <li> |
| Verify signatures: On Un*x platforms the following command can be executed: |
| <source>for file in `find . -type f -iname '*.asc'` |
| do |
| gpg --verify ${file} |
| done</source> |
| You'll need to look at the output to ensure it contains only good signatures: |
| <source>gpg: Good signature from ... |
| gpg: Signature made ...</source> |
| </li> |
| </ol> |
| </li> |
| <li> |
| Once any failures or required updates have been committed to svn, rollback the release prepare files: |
| <source>mvn -P apache-release release:rollback</source> |
| </li> |
| </ol> |
| </li> |
| <li> |
| Run the |
| <tt>release:prepare</tt> step for real this time. You'll be prompted for the same version information and |
| optionally your GPG passphrase again. |
| <source>mvn -P apache-release release:prepare</source> |
| </li> |
| <li> |
| Backup (zip or tar) your local release candidate directory in case you need to rollback the release after |
| the next step is performed. |
| <source>cd .. |
| tar -czf <version>.tar.gz <version>/ |
| cd <version></source> |
| </li> |
| </ol> |
| </subsection> |
| |
| <subsection name="Perform the release"> |
| <ol> |
| <li> |
| This step will create the staging site |
| <source>svn checkout https://svn.apache.org/repos/asf/incubator/syncope/site/ site |
| svn checkout https://svn.apache.org/repos/asf/incubator/syncope/tags/syncope-<version> syncope-<version> |
| cd syncope-<version> |
| mvn -Pall clean install |
| mvn -f parent/pom.xml -P site -Dsite.deploymentBaseUrl=file:///<absolute path to ../site/<version>> |
| cd ../site/<version> |
| rm -r syncope-console syncope-client syncope-archetype syncope-core syncope-build-tools syncope-hibernate-enhancer syncope-quality |
| cd .. |
| svn add <version> |
| svn commit -m "staging site for release"</source> |
| </li> |
| <li> |
| From the directory where you have launched <tt>release:prepare</tt> execute (this step will create a maven staging repository): |
| <source>mvn -P apache-release release:perform [-Duser.name=<your_apache_uid>]</source> |
| |
| <p> |
| <em>If your local OS userid doesn't match your Apache userid, then you'll have to also override the value |
| provided by the OS to Maven for the site-deploy step to work. This is known to work for Linux, |
| but not for Mac and unknown for Windows. |
| </em> |
| </p> |
| |
| <ol> |
| <li>Verify the staged artifacts in the Nexus repository: |
| <ol> |
| <li> |
| <a href="https://repository.apache.org/index.html">https://repository.apache.org/index.html</a> |
| </li> |
| <li> |
| <strong>Enterprise --> Staging</strong> |
| </li> |
| <li> |
| <strong>Staging tab --> Name column --> org.apache.syncope</strong> |
| </li> |
| <li>Navigate through the artifact tree and make sure that all binary, |
| <code>javadoc</code>, |
| <code>sources</code>, and |
| <code>tests</code> jars, as well as |
| <code>pom</code>s, ... have |
| <code>.asc</code> (GPG signature) and |
| <code>.md5</code> |
| files (see |
| <a href="http://people.apache.org/~henkp/repo/faq.html">Repository FAQ</a> and |
| <a href="http://www.apache.org/dev/release-signing.html#openpgp-ascii-detach-sig">Detached Signatures</a>). |
| The <code>syncope-root-<version>-source-release.zip</code> of <code>syncope-root</code> |
| should likewise have signature and checksum files. |
| </li> |
| </ol> |
| </li> |
| <li>Close the nexus staging repo: |
| <ol> |
| <li> |
| <a href="https://repository.apache.org/index.html">https://repository.apache.org/index.html</a> |
| </li> |
| <li> |
| <strong>Enterprise --> Staging</strong> |
| </li> |
| <li> |
| <strong>Staging tab --> Name column --> org.apache.syncope</strong> |
| </li> |
| <li>Right click on the open |
| <code>org.apache.syncope-XXX</code> staging repo |
| and select |
| <strong>Close</strong>. |
| </li> |
| </ol> |
| </li> |
| </ol> |
| </li> |
| </ol> |
| </subsection> |
| |
| <subsection name="Vote the release"> |
| <ol> |
| <li> |
| Create a |
| <code>VOTE</code> email thread on |
| <a href="mailto:syncope-dev@incubator.apache.org">syncope-dev</a> to record votes as replies, e.g.: |
| <pre>To: syncope-dev@incubator.apache.org |
| Subject: [VOTE] Apache Syncope <version> |
| |
| I've created a <version> release, with the following artifacts up for a vote: |
| |
| SVN source tag (r9999999): |
| https://svn.apache.org/repos/asf/incubator/syncope/tags/<version>/ |
| |
| List of changes: |
| https://svn.apache.org/repos/asf/incubator/syncope/tags/<version>/CHANGES |
| |
| Maven staging repo: |
| https://repository.apache.org/content/repositories/orgapachesyncope-YYY/ |
| |
| Source release (checksums and signatures are available at the same location): |
| https://repository.apache.org/content/repositories/orgapachesyncope-YYY/org/apache/syncope/syncope-root/<version>/syncope-root-<version>-source-release.zip |
| |
| Staging site: |
| http://incubator.apache.org/syncope/<version>/ |
| |
| PGP release keys (signed using ABCDEFG): |
| http://www.apache.org/dist/incubator/syncope/KEYS |
| |
| Vote will be open for 72 hours. |
| |
| [ ] +1 approve |
| [ ] +0 no opinion |
| [ ] -1 disapprove (and reason why)</pre> |
| </li> |
| <li> |
| Create a <code>DISCUSS</code> email thread on <a href="mailto:syncope-dev@incubator.apache.org">syncope-dev</a> for any vote questions, e.g.: |
| <pre> |
| To: syncope-dev@incubator.apache.org |
| Subject: [DISCUSS] Apache Syncope <version> |
| |
| Discussion thread for vote on <version> release, with SVN source tag (r9999999). |
| |
| For more information on the release process, check out http://www.apache.org/dev/release.html |
| |
| Some of the things to check before voting are: |
| - does "mvn apache-rat:check" pass on the source |
| - can you build the contents of source release zip and SVN tag |
| - do all of the staged jars/wars/zips contain the required LICENSE and NOTICE files |
| - are all of the staged jars/wars/zips signed and the signature verifiable |
| - is the signing key in the project's KEYS file and on a public server (i.e. http://www.apache.org/dist/incubator/syncope/) |
| </pre> |
| </li> |
| <li> |
| Perform a review of the release and cast your vote. For more details on Apache releases see |
| <a href="http://www.apache.org/dev/release.html">http://www.apache.org/dev/release.html</a>. |
| </li> |
| <li>A -1 vote does not necessarily mean that the vote must be redone, |
| however it is usually a good idea to rollback the release if a -1 vote is |
| received (see <a href="#Recovering_from_a_vetoed_release">"Recovering from a vetoed release"</a>). |
| </li> |
| <!-- <incubator-specific> --> |
| <li>After the vote has been open for at least 72 hours, has at least three |
| +1 PMC votes and no -1 votes, then post the results to the vote thread: |
| <pre>To: syncope-dev@incubator.apache.org |
| Subject: [RESULT] [VOTE] Apache Syncope <version> |
| |
| Hi all, |
| after 72 hours, the vote for Syncope <version> [1] *passes* |
| with ... PPMC + ... non-PPMC votes. |
| |
| +1 (PPMC / binding) |
| * ... |
| |
| +1 (non binding) |
| * ... (or <none>) |
| |
| 0 |
| * ... (or <none>) |
| |
| -1 |
| * ... (or <none>) |
| |
| Thanks to everyone participating. |
| |
| I will now submit the release for voting on the general@incubator.apache.org |
| |
| Best regards. |
| |
| [1] <link to syncope-dev ML archives for the related [VOTE] thread></pre> |
| </li> |
| <li>Once the vote has been approved on <a href="mailto:syncope-dev@incubator.apache.org">syncope-dev</a>, |
| then the release process should be performed again on |
| <a href="mailto:general@incubator.apache.org">general@incubator</a> ML. |
| <pre>To: general@incubator.apache.org |
| Subject: [VOTE] Apache Syncope <version> |
| |
| I've created a <version> release, with the following artifacts up for a vote: |
| |
| SVN source tag (r9999999): |
| https://svn.apache.org/repos/asf/incubator/syncope/tags/<version>/ |
| |
| List of changes: |
| https://svn.apache.org/repos/asf/incubator/syncope/tags/<version>/CHANGES |
| |
| Maven staging repo: |
| https://repository.apache.org/content/repositories/orgapachesyncope-YYY/ |
| |
| Source release (checksums and signatures are available at the same location): |
| https://repository.apache.org/content/repositories/orgapachesyncope-YYY/org/apache/syncope/syncope-root/<version>/syncope-root-<version>-source-release.zip |
| |
| Staging site: |
| http://incubator.apache.org/syncope/<version>/ |
| |
| PGP release keys (signed using ABCDEFG): |
| http://www.apache.org/dist/incubator/syncope/KEYS |
| |
| This has been voted through on the syncope-dev@incubator.apache.org mailing list [1], |
| and now requires a vote on general@incubator.apache.org |
| |
| Votes already cast (on syncope-dev): |
| |
| +1 (binding) |
| * ... |
| |
| +1 (non binding) |
| * ... (or <none>) |
| |
| |
| Vote will be open for 72 hours. |
| |
| [ ] +1 approve |
| [ ] +0 no opinion |
| [ ] -1 disapprove (and reason why) |
| |
| Best regards. |
| |
| [1] <link to syncope-dev ML archives for the related [RESULT] [VOTE] thread></pre> |
| </li> |
| <li>Once the incubator vote has completed, post the results to the |
| <a href="mailto:general@incubator.apache.org">general@incubator</a> ML: |
| <pre>To: general@incubator.apache.org |
| Subject: [RESULT] [VOTE] Apache Syncope <version> |
| |
| Hi all, |
| after 72 hours, the vote for Syncope <version> [1] *passes* |
| with ... IPMC + ... non-IPMC votes. |
| |
| +1 (IPMC / binding) |
| * ... |
| |
| +1 (non binding) |
| * ... (or <none>) |
| |
| 0 |
| * ... (or <none>) |
| |
| -1 |
| * ... (or <none>) |
| |
| Thanks to everyone participating. |
| |
| I will now copy this release to Syncope' dist directory and promote the artifacts to the central Maven repository. |
| |
| Best regards. |
| |
| [1] <link to general incubator ML archives for the related [VOTE] thread></pre> |
| </li> |
| <!-- </incubator-specific> --> |
| </ol> |
| </subsection> |
| |
| <subsection name="Finalize the release"> |
| <ol> |
| <li>Promote the staged nexus artifacts: |
| <ol> |
| <li> |
| <a href="https://repository.apache.org/index.html">https://repository.apache.org/index.html</a> |
| </li> |
| <li> |
| <strong>Enterprise --> Staging</strong> |
| </li> |
| <li> |
| <strong>Staging tab --> Name column --> org.apache.syncope</strong> |
| </li> |
| <li>Right click on the closed |
| <code>org.apache.syncope-XXX</code> staging repo and select |
| <strong>Release</strong>. |
| </li> |
| </ol> |
| </li> |
| <li> |
| Add the distribution artifacts to the distribution area |
| <source>ssh people.apache.org |
| cd /x1/www/www.apache.org/dist/incubator/syncope/ |
| wget -e robots=off -nH --cut-dirs=7 -np --no-check-certificate -m -A *.zip* -R .asc.sha1,.asc.md5 \ |
| https://repository.apache.org/content/repositories/releases/org/apache/syncope/syncope-root/<version>/ |
| </source> |
| </li> |
| <li> |
| Remove older distribution artifacts (if present) from the distribution area (i.e. |
| <tt>people.apache.org:/x1/www/www.apache.org/dist/incubator/syncope/</tt>). |
| </li> |
| <li> |
| Add appropriate release notes to |
| <a href="https://cwiki.apache.org/confluence/display/SYNCOPE/Releases">Releases</a> |
| wiki page based on the HTML release reports from JIRA |
| </li> |
| <li> |
| Update the <a href="https://cwiki.apache.org/confluence/display/SYNCOPE/Create+a+new+Syncope+project">Create |
| new project</a> wiki page to point to the new release artifacts |
| </li> |
| <li> |
| Update the <a href="https://issues.apache.org/jira/plugins/servlet/project-config/SYNCOPE/versions">JIRA |
| versions</a> page to mark the version as <strong>Released</strong>, and set the date to the date that |
| the release was approved. You may also need to make a new release entry for the next release. |
| </li> |
| <li> |
| Promote the staging site |
| <source> |
| svn co https://svn.apache.org/repos/asf/incubator/syncope/site/ |
| cd site |
| svn rm *.html apidocs css images js |
| svn mv <version>/* . |
| svn rm <version> |
| svn commit -m "Promoting the staging site"</source> |
| </li> |
| </ol> |
| </subsection> |
| |
| <subsection name="Announce the release"> |
| After the mirrors have had time to update (24 hours to be on the safe side), make an announcement about the release on the |
| <a href="mailto:syncope-user@incubator.apache.org">syncope-user</a>, |
| <a href="mailto:syncope-dev@incubator.apache.org">syncope-dev</a>, and |
| <a href="mailto:announce@apache.org">announce@apache.org</a> lists as per |
| <a href="http://www.apache.org/foundation/mailinglists.html#foundation-announce">the Apache Announcement Mailing Lists page</a> |
| </subsection> |
| </section> |
| |
| <section name="Recovering from a vetoed release"> |
| <ol> |
| <li> |
| <p>Reply to the initial vote email prepending |
| <code>[CANCELED]</code> to the original subject. |
| </p> |
| </li> |
| <li> |
| <p>Rollback the version upgrades in trunk by |
| <em>either</em>: |
| </p> |
| <ol> |
| <li> |
| restore the <version>.tar.gz and run |
| <source>mvn -P apache-release release:rollback</source> |
| </li> |
| <li> |
| <em>or</em> |
| manually revert the versions in trunk to the prior version and commit |
| </li> |
| </ol> |
| </li> |
| <li> |
| <p>Delete the svn tag created by the |
| <code>release:perform</code> step: |
| </p> |
| <source>svn rm https://svn.apache.org/repos/asf/incubator/syncope/tags/<version> -m "deleting tag from rolled back release"</source> |
| </li> |
| <li> |
| <p>Delete the staging site: |
| </p> |
| <source>svn rm https://svn.apache.org/repos/asf/incubator/syncope/site/<version> -m "deleting staging site from rolled back release"</source> |
| </li> |
| <li> |
| <p>Drop the nexus staging repo:</p> |
| <ol> |
| <li> |
| <a href="https://repository.apache.org/index.html">https://repository.apache.org/index.html</a> |
| </li> |
| <li> |
| <strong>Enterprise --> Staging</strong> |
| </li> |
| <li> |
| <strong>Staging tab --> Name column --> org.apache.syncope</strong> |
| </li> |
| <li>Right click on the closed |
| <code>org.apache.syncope-XXX</code> staging repo and select |
| <strong>Drop</strong>. |
| </li> |
| </ol> |
| </li> |
| <li> |
| Make the required updates that caused the vote to be canceled. |
| </li> |
| <li>Spin another release attempt!</li> |
| </ol> |
| </section> |
| </body> |
| </document> |