You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by fm...@apache.org on 2013/01/11 13:08:28 UTC
svn commit: r1432008 -
/felix/site/trunk/content/documentation/development/release-management-nexus.mdtext
Author: fmeschbe
Date: Fri Jan 11 12:08:28 2013
New Revision: 1432008
URL: http://svn.apache.org/viewvc?rev=1432008&view=rev
Log:
Update description of release process after switching to Apache CMS and SVN PubSub
Modified:
felix/site/trunk/content/documentation/development/release-management-nexus.mdtext
Modified: felix/site/trunk/content/documentation/development/release-management-nexus.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/development/release-management-nexus.mdtext?rev=1432008&r1=1432007&r2=1432008&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/development/release-management-nexus.mdtext (original)
+++ felix/site/trunk/content/documentation/development/release-management-nexus.mdtext Fri Jan 11 12:08:28 2013
@@ -3,6 +3,21 @@ Title: Release Management (Nexus)
*This is the new release process for Apache Felix, based on the updated Maven [process](http://maven.apache.org/developers/release/releasing.html)*
+## Basics
+
+Apache Felix artifacts are distributed in two channels: The Maven Repository and the Apache
+distribution channels.
+
+The basic steps for releasing are:
+
+* [Release the module with the Maven Release plugin deploying to the Nexus Staging repository](#staging-the-release-candidates)
+* Check the artifacts
+* [Call for vote](#starting-the-vote)
+* [Publish the release candidate](#promoting-the-release):
+ * Publish the staged artifacts from Nexus Staging
+ * `svn add` the artifacts to Subversion repository and `svn rm` the artifacts from the previous release
+* [Announce the release](#create-an-announcement)
+
## Prerequisites
To prepare or perform a release you *MUST BE* at least an Apache Felix Committer.
@@ -17,7 +32,7 @@ To prepare or perform a release you *MUS
In the past we staged release candidates on our local machines using a semi-manual process. Now that we inherit from the Apache parent POM version 5, a repository manager will automatically handle staging for you. This means you now only need to specify your GPG passphrase in the release profile of your `$\{user.home\}/.m2/settings.xml`:
-
+ :::xml
<settings>
...
<profiles>
@@ -34,7 +49,7 @@ In the past we staged release candidates
Everything else has been configured in the latest Felix parent POM:
-
+ :::xml
<parent>
<groupId>org.apache.felix</groupId>
<artifactId>felix-parent</artifactId>
@@ -51,41 +66,36 @@ First prepare your POMs for release:
1. Make sure you have an updated change log file, typically in `doc/changelog.txt` but in the project root is also acceptable.
1. make sure there are no snapshots in the POMs to be released
1. check that your POMs will not lose content when they are rewritten during the release process
-1. * `mvn release:prepare -DdryRun=true`
-1. * diff the original `pom.xml` with the one called `pom.xml.tag` to see if the license or any other info has been removed. This has been known to happen if the starting `<project>` tag is not on a single line. The only things that should be different between these files are the `<version>` and `<scm>` elements. If there are any other changes, you must fix the original `pom.xml` file and commit before proceeding with the release
+ * `mvn release:prepare -DdryRun=true`
+ * diff the original `pom.xml` with the one called `pom.xml.tag` to see if the license or any other info has been removed. This has been known to happen if the starting `<project>` tag is not on a single line. The only things that should be different between these files are the `<version>` and `<scm>` elements. If there are any other changes, you must fix the original `pom.xml` file and commit before proceeding with the release
1. publish a snapshot
-
- $ mvn deploy
- ...
- [INFO] [deploy:deploy]
- [INFO] Retrieving previous build number from apache.snapshots.https
- ...
-
-1. * if you experience an error during deployment like a HTTP 401 check your settings for the required server entries as outlined in the *Prerequisites*
-1. * be sure that the generated artifacts respect the Apache release [rules](http://www.apache.org/dev/release.html): NOTICE and LICENSE files should be present in the META-INF directory within the jar. For -sources artifacts, be sure that your POM does not use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4
-1. * you should verify the deployment under the [snapshot](https://repository.apache.org/content/groups/snapshots/org/apache/felix) repository on Apache
+ <div class="codehilite"><code>$ mvn deploy
+ ...
+ [INFO] [deploy:deploy]
+ [INFO] Retrieving previous build number from apache.snapshots.https
+ ...</code></div>
+ * if you experience an error during deployment like a HTTP 401 check your settings for the required server entries as outlined in the *Prerequisites*
+ * be sure that the generated artifacts respect the Apache release [rules](http://www.apache.org/dev/release.html): NOTICE and LICENSE files should be present in the META-INF directory within the jar. For -sources artifacts, be sure that your POM does not use the maven-source-plugin:2.0.3 which is broken. The recommended version at this time is 2.0.4
+ * you should verify the deployment under the [snapshot](https://repository.apache.org/content/groups/snapshots/org/apache/felix) repository on Apache
1. prepare the release
-
- mvn release:clean
- mvn release:prepare
-
-1. * preparing the release will create the new tag in SVN, automatically checking in on your behalf
+ <div class="codehilite"><code>$ mvn release:clean
+ $ mvn release:prepare</code></div>
+ * preparing the release will create the new tag in SVN, automatically checking in on your behalf
1. stage the release for a vote
-
- mvn release:perform
-
-1. * the release will automatically be inserted into a temporary staging repository for you, see the Nexus [staging documentation](http://www.sonatype.com/books/nexus-book/reference/staging.html) for full details
-1. * you can continue to use `mvn release:prepare` and `mvn release:perform` on other sub-projects as necessary on the same machine and they will be combined in the same staging repository - this is useful when making a release of the Felix framework and its associated bundles.
+ <div class="codehilite"><code>$ mvn release:perform</code></div>
+ * the release will automatically be inserted into a temporary staging repository for you, see the Nexus [staging documentation](http://www.sonatype.com/books/nexus-book/reference/staging.html) for full details
+ * you can continue to use `mvn release:prepare` and `mvn release:perform` on other sub-projects as necessary on the same machine and they will be combined in the same staging repository - this is useful when making a release of the Felix framework and its associated bundles.
1. close the staging repository
-1. * login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.felix* in the list of repositories. In the panel below you should see an open repository that is linked to your username and IP. Right click on this repository and select *Close*. This will close the repository from future deployments and make it available for others to view. If you are staging multiple releases together, skip this step until you have staged everything
+ * login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.felix* in the list of repositories. In the panel below you should see an open repository that is linked to your username and IP. Right click on this repository and select *Close*. This will close the repository from future deployments and make it available for others to view. If you are staging multiple releases together, skip this step until you have staged everything
1. verify the staged artifacts
-1. * if you click on your repository, a tree view will appear below. You can then browse the contents to ensure the artifacts are as you expect them. Pay particular attention to the existence of \*.asc (signature) files. If you don't like the content of the repository, right click your repository and choose *Drop*. You can then rollback your release (see *Canceling the Release*) and repeat the process
-1. * note the staging repository URL (especially the number at the end of the URL) you will need this in your vote email
+ * if you click on your repository, a tree view will appear below. You can then browse the contents to ensure the artifacts are as you expect them. Pay particular attention to the existence of \*.asc (signature) files. If you don't like the content of the repository, right click your repository and choose *Drop*. You can then rollback your release (see *Canceling the Release*) and repeat the process
+ * note the staging repository URL (especially the number at the end of the URL) you will need this in your vote email
## Starting the Vote
Propose a vote on the dev list with the closed issues, the issues left, and the staging repository - for example:
+ :::text
To: "Felix Developers List" <de...@felix.apache.org>
Subject: [VOTE] Release Felix XXX version Y.Z
@@ -113,19 +123,21 @@ Propose a vote on the dev list with the
This vote will be open for 72 hours.
-* to get the JIRA release notes link, browse to the FELIX [JIRA](http://issues.apache.org/jira/browse/FELIX) page, select [Release Notes|http://issues.apache.org/jira/secure/ConfigureReleaseNote.jspa?projectId=12310100] and choose the relevant sub-project release and format (HTML)
-* to get the list of issues left in JIRA, select the [Open Issues](http://issues.apache.org/jira/browse/FELIX?report=com.atlassian.jira.plugin.system.project:openissues-panel) tab on the main FELIX page, and select the relevant sub-project.
+To get the JIRA release notes link, browse to the FELIX [JIRA](http://issues.apache.org/jira/browse/FELIX) page, select [Release Notes|http://issues.apache.org/jira/secure/ConfigureReleaseNote.jspa?projectId=12310100] and choose the relevant sub-project release and format (HTML)
+
+To get the list of issues left in JIRA, select the [Open Issues](http://issues.apache.org/jira/browse/FELIX?report=com.atlassian.jira.plugin.system.project:openissues-panel) tab on the main FELIX page, and select the relevant sub-project.
## Wait for the Results
From [Votes on Package Releases](http://www.apache.org/foundation/voting.html):
-{quote}Votes on whether a package is ready to be released follow a format similar to majority approval -- except that the decision is officially determined solely by whether at least three +1 votes were registered. Releases may not be vetoed. Generally the community will table the vote to release if anyone identifies serious problems, but in most cases the ultimate decision, once three or more positive votes have been garnered, lies with the individual serving as release manager. The specifics of the process may vary from project to project, but the 'minimum of three +1 votes' rule is universal.{quote}
+> Votes on whether a package is ready to be released follow a format similar to majority approval -- except that the decision is officially determined solely by whether at least three +1 votes were registered. Releases may not be vetoed. Generally the community will table the vote to release if anyone identifies serious problems, but in most cases the ultimate decision, once three or more positive votes have been garnered, lies with the individual serving as release manager. The specifics of the process may vary from project to project, but the 'minimum of three +1 votes' rule is universal.
-The list of binding voters is available at [http://felix.apache.org/site/project-management-committee-pmc.html](http://felix.apache.org/site/project-management-committee-pmc.html)
+The list of binding voters is available at [{{ project-management-committee-pmc.headers.title }}]({{ project-management-committee-pmc.path }})
If the vote is successful, post the result to the dev list - for example:
+ :::text
To: "Felix Developers List" <de...@felix.apache.org>
Subject: [RESULT] [VOTE] Release Felix XXX version Y.Z
@@ -145,7 +157,8 @@ If the vote is successful, you need to p
## Canceling the Release
If the vote fails, or you decide to redo the release:
-1. remove the release tag from Subversion (`svn del ...`)
+
+1. remove the release tag from Subversion (`svn rm ...`)
1. login to [https://repository.apache.org](https://repository.apache.org) using your Apache SVN credentials. Click on *Staging* on the left. Then click on *org.apache.felix* in the list of repositories. In the panel below you should see a closed repository that is linked to your username and IP (if it's not yet closed you need to right click and select *Close*). Right click on this repository and select *Drop*.
1. rollback the version in the `pom.xml` and commit any fixes you need to make
@@ -153,19 +166,88 @@ If the vote fails, or you decide to redo
The release manager is free to either reuse the same version when proposing a new release for vote (for example 2.1.2 after a failed 2.1.2 release attempt), or choose a different number (for example 2.1.4 after a failed 2.1.2 attempt). (cf. vote on 02/14/11).
</div>
+
## Promoting the Release
If the vote passes:
-1. copy the released artifacts to the Felix dist directory (`/x1/www/www.apache.org/dist/felix`) on `people.apache.org`
-1. delete the old release from the Felix dist directory (it's archived)
-1. login to [https://repository.apache.org](https://repository.apache.org) with your Apache SVN credentials. Click on *Staging*. Find your closed staging repository, select it, and click the *Release* button.
-1. next click on *Repositories*, select the *Releases* repository and validate that your artifacts are all there
-1. if you're releasing bundles, you can also add them to the Felix Release OBR (see *Appendix C*).
-1. update the news section on the website at [news](http://cwiki.apache.org/confluence/display/FELIX/news)
-1. update the download page on the website at [downloads](http://cwiki.apache.org/confluence/display/FELIX/downloads) to point to the new release.
+
+* [Upload the Artifacts](#upload-the-artifacts)
+* [Release to the Maven Repository](#release-to-the-maven-repository)
+* [Release Bundles to the OBR](#release-bundle-to-the-obr)
+* [Update the Site](#update-the-site)
+
+### Upload the Artifacts
+
+We use the distribution mechanism as described in [How do I upload a release (newer way)?](http://www.apache.org/dev/release.html#upload-ci)
+
+1. Checkout (https://dist.apache.org/repos/dist/release/felix)
+1. `svn add` the artifacts to your checkout
+1. `svn rm` the artifacts from the previous release from your checkout. This
+will remove the artifacts from the main distribution and the mirrors. They
+are still kept in the archive.
+1. `svn commit` your changes
+
+After committing your changes, the [Apache Felix Dist](http://www.apache.org/dist/felix)
+folder is immediately updated. Updating the mirrors takes another few hours
+(up to a day).
+
+### Release to the Maven Repository
+
+1. Login to (https://repository.apache.org) with your Apache SVN credentials.
+1. Click on *Staging*.
+1. Find your closed staging repository, select it, and click the *Release* button.
+1. Click on *Repositories*
+1. Select the *Releases* repository
+1. Validate that your artifacts are all there
+
+### Release Bundles to the OBR
+
+If you're releasing bundles, you can also add them to the Felix Release OBR. To do this, execute the following command:
+
+ :::bash
+ $ export site=# your checkout of (https://svn.apache.org/repos/asf/felix/site/trunk/content)
+ $ export obr=${site}/obr
+ $ mvn clean install \
+ org.apache.felix:maven-bundle-plugin:deploy \
+ -DprefixUrl=http://repo1.maven.org/maven2 \
+ -DremoteOBR=releases.xml \
+ -DaltDeploymentRepository=apache.website::default::file:///${obr}
+ $ svn commit -m"..." ${obr}/repository.xml
+
+After committing the site must be published. If you release to OBR before
+[updating the site](update-the-site) you can defer publishing until after that.
+Otherwise publish the site by visiting the [Site Publication](https://cms.apache.org/felix/publish)
+link.
+
+The (http://felix.apache.org/obr/releases.xml) page immediately updated.
+
+**Note**: the project building the bundle must use the [{{ maven-bundle-plugin.headers.title }}]({{ maven-bundle-plugin.path }}) and use a version equal to or higher than 1.4.2.
+
+**Note**: with Maven 3, you must add an extension to your `<build>` providing the SCP/SSH protocol:
+
+ :::xml
+ <build>
+ ...
+ <extensions>
+ <extension>
+ <groupId>org.apache.maven.wagon</groupId>
+ <artifactId>wagon-ssh</artifactId>
+ <version>1.0-beta-6</version>
+ </extension>
+ </extensions>
+ </build>
+
+
+### Update the Site
+
+1. Update the news section on the website at [news](https://cms.apache.org/redirect?uri=http%3A//felix.apache.org/news.html)
+1. Update the download page on the website at [downloads](https://cms.apache.org/redirect?uri=http%3A//felix.apache.org/downloads.list) to point to the new release.
+1. Commit your changes (click the commit link)
+1. Publish the site (https://cms.apache.org/felix/publish)
For the last two tasks, it's better to give the mirrors some time to distribute the uploaded artifacts (one day should be fine). This ensures that once the website (news and download page) is updated, people can actually download the artifacts.
+
## Update JIRA
Go to [Admin](https://issues.apache.org/jira/secure/project/ViewProject.jspa?pid=12310100) section on the FELIX JIRA and mark the Y.Z version as released - create version Y.Z+1, if that hasn't already been done.
@@ -173,6 +255,7 @@ Go to [Admin](https://issues.apache.org/
## Create an Announcement
+ :::text
To: "Felix Users List" <us...@felix.apache.org>
Subject: [ANN] Felix XXX version Y.Z Released
@@ -201,30 +284,35 @@ Go to [Admin](https://issues.apache.org/
Remember to forward this announcement to `users@felix.apache.org` - try not to cross-post (CC:\) announcements to both user and dev lists.
-*Remind Richard about this release when he writes the next board report ;)*
+*Remind Felix about this release when he writes the next board report ;)*
## Appendix A: create and add your key to http://www.apache.org/dist/felix/KEYS
If you are using a *nix system with a working OpenSSH, GnuPG, and bash you can create and add your own key with the following command:
-1. *Create a public/private pair key*:
- gpg --gen-key
+ :::bash
+ $ gpg --gen-key
- When gpg asks for e-mail linked the key you *MUST USE* the <committer>@apache.org one
- When gpg asks for comment linked the key you *SHOULD USE* "CODE SIGNING KEY"
-1. *Add the key to* http://www.apache.org/dist/felix/KEYS: type the following command replacing the word e-mail with your Apache's one (<committer>@apache.org).
+When gpg asks for e-mail linked the key you *MUST USE* the <committer>@apache.org one.
+When gpg asks for comment linked the key you *SHOULD USE* "CODE SIGNING KEY".
+
+Second, *Add the key to* (https://dist.apache.org/repos/dist/release/felix/KEYS): type the following command replacing the word e-mail with your Apache's one (<committer>@apache.org). To update you have to checkout the Felix
+dist release repository (you also need this to publish a release):
+
+ :::bash
+ $ (gpg --list-sigs e-mail && gpg --export --armor e-mail) > toadd.key
+ $ svn checkout https://dist.apache.org/repos/dist/release/felix felix-dist
+ $ cat toadd.key >> felix-dist/KEYS
+ $ scn commit -m"KEYS += <committer>" felix-dist/KEYS
- (gpg --list-sigs e-mail && gpg --export --armor e-mail) > toadd.key
- scp toadd.key people.apache.org:
- ssh people.apache.org "cat toadd.key >> /x1/www/www.apache.org/dist/felix/KEYS"
+You are now *DONE* and the changes are visible on http://www.apache.org/dist/felix/KEYS.
-1. You are now *DONE*, but to see the changes on http://www.apache.org/dist/felix/KEYS you must wait 2 hours
## Appendix B: preparing releases on Mac OS X
When running the `mvn release:prepare` command on Mac OS X, you might see the following error:
-
+ :::text
[INFO] Working directory: /homedir/dev/felix/dependencymanager
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
@@ -236,30 +324,4 @@ When running the `mvn release:prepare` c
svn: Commit failed (details follow):
svn: MKACTIVITY of '/repos/asf/!svn/act/4f11ad5d-9161-0410-b4dd-cb727141ea8c': authorization failed (https://svn.apache.org){code}
- This is due to a bug in Subversion on the Mac, as described by Brett Porter in his [blog|http://blogs.exist.com/bporter/2008/02/25/working-around-non-interactive-problems-in-leopards-subversion/]. He proposes putting an "svn" script at the head of your path to fix the issue.
-
- h2. Appendix C: deploying bundles to the Felix OBR
-
- If you're releasing bundles, you can also add them to the Felix Release OBR. To do this, execute the following command:
-
-mvn clean install \
- org.apache.felix:maven-bundle-plugin:deploy \
- -DprefixUrl=http://repo1.maven.org/maven2 \
- -DremoteOBR=releases.xml \
- -DaltDeploymentRepository=apache.website::default::scp://people.apache.org/www/felix.apache.org/obr
-
- The [http://felix.apache.org/obr/releases.xml] page is automatically updated during the web site synchronization.
- *Note*: the project building the bundle must use the [maven-bundle-plugin|Apache Felix Maven Bundle Plugin (BND)] and use a version superior or equal to 1.4.2.
- *Note*: with Maven 3, you must add an extension to your {{<build>}} providing the SCP/SSH protocol:
-
-<build>
-...
- <extensions>
- <extension>
- <groupId>org.apache.maven.wagon</groupId>
- <artifactId>wagon-ssh</artifactId>
- <version>1.0-beta-6</version>
- </extension>
- </extensions>
-</build>
-
+This is due to a bug in Subversion on the Mac, as described by Brett Porter in his [blog|http://blogs.exist.com/bporter/2008/02/25/working-around-non-interactive-problems-in-leopards-subversion/]. He proposes putting an "svn" script at the head of your path to fix the issue.