Dear Wiki user, You have subscribed to a wiki page or wiki category on "Commons Wiki" for change notification.
The "UsingNexus" page has been changed by GaryGregory. The comment on this change is: Add example you can cut and paste.. http://wiki.apache.org/commons/UsingNexus?action=diff&rev1=17&rev2=18 -------------------------------------------------- = Using Nexus for Commons Maven releases = - '''DRAFT''' Notes on using Nexus @@ -9, +8 @@ NOTE - much of this content can be replaced simply by referencing the new unified docs: [[http://www.apache.org/dev/publishing-maven-artifacts.html|Publishing Maven Artifacts]] == What is Nexus? == - Nexus is a repository manager, and acts as a staging repository which "intercepts" artifacts uploaded by '''mvn deploy'''. + Thus artifacts can be safely deployed to Nexus as part of voting on a release. The vote takes place on the staged artifacts. If the vote succeeds, the artifacts can be promoted to the live repository. If it fails, the artifacts can be deleted, and the process can restart. - Thus artifacts can be safely deployed to Nexus as part of voting on a release. - The vote takes place on the staged artifacts. - If the vote succeeds, the artifacts can be promoted to the live repository. - If it fails, the artifacts can be deleted, and the process can restart. It also allows redundant files (such as .asc.md5 and .asc.sha1 hashes) to be deleted before deployment. == Preparations for using Nexus == - - * All Commons components that use the ''org.apache.commons'' groupId are already set up to use Nexus. + * All Commons components that use the ''org.apache.commons'' groupId are already set up to use Nexus. + However, components that use different groupIds may need to be set up. See the instructions in [[http://www.apache.org/dev/publishing-maven-artifacts.html|Publishing Maven Artifacts]] to request adjustments to the Nexus configuration to support additional groupIds. * If you have not done so already, create a master password. - See http://maven.apache.org/guides/mini/guide-encryption.html - The master password should be stored on a USB stick if your host system is not secure. - Create the ~/.m2/settings-security.xml file, for example: {{{ + + See http://maven.apache.org/guides/mini/guide-encryption.html The master password should be stored on a USB stick if your host system is not secure. Create the ~/.m2/settings-security.xml file, for example: + + {{{ <settingsSecurity> <relocation>/USB/settings-security.xml</relocation> - </settingsSecurity>}}} + </settingsSecurity> - + }}} - This should point to the file containing the master password:{{{ + This should point to the file containing the master password: + + {{{ <settingsSecurity> <master>Master password goes here</master> - </settingsSecurity>}}} + </settingsSecurity> - + }}} If you are sure that your system is secure, then the master password can be stored directly in the ~/.m2/settings-security.xml file. * Ensure that you have set up your Apache username and password in your settings.xml file. There are two sections that need to be defined: + * apache.snapshots.https * apache.releases.https + These correspond with Nexus repository definitions in the Apache parent pom (v7). {{{ @@ -60, +60 @@ <password>{encryptedpassword}</password> </server> }}} - == How to use deploy using Nexus == - - As noted above, there are two different repositories, one for snapshots and the other for releases. - If the version contains the suffix '''-SNAPSHOT''', then the snapshot repo will be chosen by '''mvn deploy''' otherwise deploy will use the release repo. + As noted above, there are two different repositories, one for snapshots and the other for releases. If the version contains the suffix '''-SNAPSHOT''', then the snapshot repo will be chosen by '''mvn deploy''' otherwise deploy will use the release repo. === Creating a Nexus snapshot === + In the run-up to a release, it is worth-while creating a snapshot. This will allow checking of the artifacts, as well as checking that the settings are correct. - - In the run-up to a release, it is worth-while creating a snapshot. - This will allow checking of the artifacts, as well as checking that the settings are correct. To create the snapshot, make sure that the current pom.xml is for a SNAPSHOT version. Perform the following command: @@ -77, +72 @@ This will create the binary, source and javadoc jars and hashes and upload them. - The {{{-Prelease}}} flag is necessary to ensure that the source and javadoc jars are created. + The {{{-Prelease}}} flag is necessary to ensure that the source and javadoc jars are created. The {{{-Dgpg.skip}}} flag skips the signing phase. - The {{{-Dgpg.skip}}} flag skips the signing phase. The resulting snapshot will appear in the Nexus repository under: @@ -87, +81 @@ If the upload fails with {{{Error deploying artifact: Failed to transfer file: ... Return code is: 401}}} then either the username/password are incorrect, or Nexus has not yet been set up for the commons component. === Deploying to a local directory === + The deploy target can easily be overridden by defining the altDeploymentRepository property. For example, the following will deploy to the local directory {{{target/deploy}}}: - - The deploy target can easily be overridden by defining the altDeploymentRepository property. - For example, the following will deploy to the local directory {{{target/deploy}}}: {{{mvn deploy -Prelease [-Dgpg.skip] [-DskipTests] -DaltDeploymentRepository=id::default::file:target/deploy}}} @@ -103, +95 @@ </properties> </profile> }}} - So you can add {{{-Ptest-deploy}}} to the deploy command to change the deployment to use {{{target/deploy}}}. + For example: + + {{{mvn clean deploy -Prelease }}}{{{-Ptest-deploy}}} + === Creating a Nexus staging release === - '''Make sure you are using Commons Parent V16 or later.''' This is necessary to ensure that Nexus is used as the deployment target. ==== Prepare Your Version Number ==== - - A guideline regarding version numbering can be found at [[http://commons.apache.org/releases/versioning.html]] - within Commons we reached the following consensus + A guideline regarding version numbering can be found at http://commons.apache.org/releases/versioning.html - within Commons we reached the following consensus * when your release a new major or minor version it comes without point release number, e.g "foo-1.0.jar" or "foo-2.1.jar" * when doing a bugfix release your need to add the point release number, e.g "foo-1.0.1.jar" or "foo-2.1.1.jar" ==== Prepare Your Maven Variables ==== - During the staging process a directory is created on ''people.apache.org'' based on the content of the following Maven variables * commons.release.version is a duplicate of the pom version @@ -134, +126 @@ <commons.rc.version>RC2</commons.rc.version> </properties> }}} - ==== Update Your Download Page ==== - The commons-build plugin generates a download page in {{{./src/site/xdoc/}}} based on {{{commons.release.version}}} {{{ mvn commons:download-page }}} - - ==== Update the release notes ==== + Ensure that the release notes refer to the release version, not snapshot. If using automatic release note generation from changes.xml, the following command should update the file: - - Ensure that the release notes refer to the release version, not snapshot. - If using automatic release note generation from changes.xml, the following command should update the file: {{{ mvn changes:changes-report changes:announcement-generate }}} - ==== Prepare Your Assembly Descriptors ==== - If you are declaring/using your own assembly descriptors make sure that they are not using ${version} but ${commons.release.version} - there seems to be an odd bug which results in an incorrectly expanded version string, e.g. {{{commons-exec-2.4.1-src}}}. If in doubt look at {{{./src/assembly/src.xml}}} ==== Commit Your Changes ==== - When you followed the instructions you have modified a couple of files by now - commit them now otherwise the release process will fail. ==== Create the SVN tags (Manual method) ==== - Create a clean SVN workspace for the release candidate {{{svn co https://svn.apache.org/repos/asf/commons/proper/<component>/trunk <component>-m.n.o-RC1}}} @@ -177, +159 @@ perl -pi.bak -e "s!-SNAPSHOT</version!</version!" %%i del pom.xml.bak/S }}} - Or using Maven: {{{mvn versions:set -DnewVersion=3.1 -DgenerateBackupPoms=false}}} @@ -193, +174 @@ This should result in a new tag, containing the "trunk" code with the POM fixes only. All history is preserved. ==== Create the SVN tags (using Maven Release plugin) ==== - Check that your poms will not lose content when they are rewritten during the release process. * mvn release:prepare -!DdryRun=true @@ -215, +195 @@ </properties> </profile> }}} - Or running mvn with this arguments: {{{ mvn -DdryRun=true -Dgpg.keyname=your_key \ -Darguments="-Dgpg.keyname=your_key" release:prepare }}} - ==== Deploy the artifacts ==== - Once the code appears to be ready, the Maven artifacts can be deployed: {{{mvn deploy -Prelease [-Ptest-deploy]}}} @@ -236, +213 @@ See [[http://www.apache.org/dev/publishing-maven-artifacts.html#close-stage|Closing the Staged Repository]] for information about reviewing your staged artifacts and making them available for others to review. ==== Stage the site ==== - The [[http://maven.apache.org/plugins/maven-site-plugin/usage.html|site plugin]] can be used for staging a website. You probably need to add some authentication information to your settings.xml. Please mind the id "stagingSite". {{{ @@ -250, +226 @@ --> </server> }}} - Once done, run a command like this from your tag: {{{ mvn site:stage-deploy -DstagingDirectory=src/site \ -DstagingSiteURL=scp://[...]/people.apache.org/builds/commons/compress/1.1/RC1 }}} - The site should appear on the specified folder. ==== Send Out The Vote ==== - Below you find a vote template to save you some time ... {{{ @@ -280, +253 @@ [ ] +1 release it [ ] +0 go ahead I don't care [ ] -1 no, do not release it because - }}} - ==== React to the Vote ==== - If the vote failed, you need to [[http://www.apache.org/dev/publishing-maven-artifacts.html#drop|Drop]] the repo and start again. If the vote passed the following steps need to be performed: ==== Releasing ==== - '''NOTE''' The Commons Parent pom currently attaches the assembly archives (the -bin* and -src* files) to the deploy phase, so they end up being copied to the Nexus staging repository. This is convenient for voting, as all the files are in the same place, but means that additional action needs to be taken to move the non-Maven files to the correct place. ===== wget the non-Maven artifacts from Nexus to people server ===== - - In your home directory, perform: + In your home directory, perform: + {{{ wget -np -r https://repository.apache.org/content/repositories/orgapachecommons-098/org/apache/commons/commons-foo/1.1/ }}} - Check the MD5/SHA hashes! ===== Copy to dist ===== - On people.apache.org, change directory to the distribution directory for your component: {{{ - cd /www/www.apache.org/dist/commons/foo/ + cd /www/www.apache.org/dist/commons/foo/ }}} - Move source distributions, their detached signatures and md5 sums into position. All source versions live in the source subdirectory. {{{ - mv ~/foo-1.2-RC3/commons-foo-1.2-src* source + mv ~/foo-1.2-RC3/commons-foo-1.2-src* source }}} - - Move the binary distributions, their detached signatures and md5 sums into position. All binary versions live in the binaries subdirectory. + Move the binary distributions, their detached signatures and md5 sums into position. All binary versions live in the binaries subdirectory. {{{ mv ~/foo-1.2-RC3/commons-foo-1.2-bin* binaries }}} - Double check the permissions for both binaries and source distributions. The file permissions should be "-rw-rw-r--" and the group should be "commons", for example: {{{ -rw-rw-r-- 1 userid commons 203 Feb 21 23:45 commons-foo-1.2-src.tar.gz.asc }}} - ===== Update README ===== + The contents of the README.html are displayed at the bottom of the html showing the directory listing. This document should be updated to reflect the new release. If this document is not present, then copy one from an existing release directory and edit that. Update the latest release number. Please also read through and correct any mistakes you find and fix other items (eg. urls) which need updating. Copy the revised README.html into the binary and source directories, replacing any old versions. - The contents of the README.html are displayed at the bottom of the html showing the directory listing. This document should be updated to reflect the new release. If this document is not present, then copy one from an existing release directory and edit that. - Update the latest release number. Please also read through and correct any mistakes you find and fix other items (eg. urls) which need updating. - Copy the revised README.html into the binary and source directories, replacing any old versions. ===== Update RELEASE-NOTES ===== Replace the current RELEASE-NOTES.txt with the new release notes. - + ===== Symbolic Links ===== - Remove symbolic links to current distributions {{{ - rm commons-foo-current* + rm commons-foo-current* }}} - - Recreate links to current distribution: - From committers/tools/releases in the ASF subversion repository, download the script "symlinks.sh" and install it in your home/bin directory. Make sure it is executable and your path includes your /bin subdirectory. From the top level distribution directory (/www/www.apache.org/dist/commons/foo/), execute + Recreate links to current distribution: From committers/tools/releases in the ASF subversion repository, download the script "symlinks.sh" and install it in your home/bin directory. Make sure it is executable and your path includes your /bin subdirectory. From the top level distribution directory (/www/www.apache.org/dist/commons/foo/), execute {{{ symlinks.sh 1.2 }}} - where the argument is the number of your version. ===== Nexus release ===== - 1. remove commons-compress-1.1-bin.* and commons-compress-1.1-src.* from nexus staging area 1. [[http://www.apache.org/dev/publishing-maven-artifacts.html#promote|Promote]] @@ -363, +319 @@ It may take a while for the Maven repo to be synchronised from Nexus. Sometimes the files don't all appear at once. ===== Test ===== - - Wait until the release files are available from the main Apache web site (http://www.apache.org/dist/commons/foo/), then confirm things are good. + Wait until the release files are available from the main Apache web site (http://www.apache.org/dist/commons/foo/), then confirm things are good. Check the main directory: - Check the main directory: 1. Examine the directory listing page. At the bottom should be found the information you entered into the README.html. Please check that this is correct. 1. Check the KEYS file @@ -373, +327 @@ 1. Download and verify the current distributions, the following might help committers/tools/releases/verify_sigs.sh. 1. Follow the links to the binaries and source directories. Check them in a similar manner. - ===== Publish the website ===== - Run the following to deploy the new component website: + {{{ mvn site:deploy - }}} + }}} - On people.apache.org, verify that the directory has been updated, and that the file and directory permissions are correct (readable by all, not writeable by world, but group writeable). Also, ensure that the group is set to 'commons'. For example: {{{ @@ -391, +343 @@ drwxrwsr-x 5 niallp commons 98 Aug 19 07:22 cobertura -rw-rw-r-- 1 grobmeier commons 7555 Aug 19 09:19 conventions.html }}} - Note that the files are transferred to the real web site only every few hours, so it may be a while before you see your changes appear. However if you set your webbrowser's HTTP proxy to 140.211.11.10 port 80 and access http://commons.apache.org/ you should be able to see the changes immediately. ===== Send announcement ===== + Announce the availability of the new release. Please check that the mirrors have been updated with the new release before sending the announce. There is no need to check all mirrors, but it's worthwhile checking a few of them. - - Announce the availability of the new release. - Please check that the mirrors have been updated with the new release before sending the announce. - There is no need to check all mirrors, but it's worthwhile checking a few of them. Please remember to give a brief description of your component. Please also remember to remind people about verifying the signatures. The subject should be something like [ANNOUNCEMENT] Foo 1.2 Released. Send this mail from your Apache account. Please spell check the document! @@ -406, +354 @@ The component website including the updated download page has been updated on the public site http://commons.apache.org/foo. - If the component publishes maven artifacts, these artifacts have been replicated to the central maven repo at repo1.maven.org. (Clear your local repo of the release artifacts and either activate the clirr report with the updated version info or update a local project with a dependency to the new release version to get maven to try to download the release artifacts. Or just access repo1 using a web browser.) + If the component publishes maven artifacts, these artifacts have been replicated to the central maven repo at repo1.maven.org. (Clear your local repo of the release artifacts and either activate the clirr report with the updated version info or update a local project with a dependency to the new release version to get maven to try to download the release artifacts. Or just access repo1 using a web browser.) The release announcement should go to (at least) the following mailing lists: - The release announcement should go to (at least) the following mailing lists: * annou...@apache.org * dev@commons.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
