[Commons Wiki] Update of "UsingNexus" by sebbapache

[Apache Wiki <wi...@apache.org>]

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 sebbapache.
The comment on this change is: Initial Nexus instructions.
http://wiki.apache.org/commons/UsingNexus

--------------------------------------------------

New page:
= Using Nexus for Commons Maven releases =

'''DRAFT'''

Notes on using Nexus

== 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.

== Preparations for using Nexus ==

 * 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: {{{
<settingsSecurity>
  <relocation>/USB/settings-security.xml</relocation>
</settingsSecurity>}}}

This should point to the file containing the master password:{{{
<settingsSecurity>
    <master>Master password goes here</master>
</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).

{{{
<!-- To publish a snapshot -->
<server>
  <id>apache.snapshots.https</id>
  <username><!-- ASF login name --></username>
  <password>{encryptedpassword}</password>
</server>
<!-- To publish a release -->
<server>
  <id>apache.releases.https</id>
  <username><!-- ASF login name --></username>
  <password>{encryptedpassword}</password>
</server>
}}}

== Enabling Nexus use for your project ==

If Nexus has not been enabled, then ask by filing a JIRA subtask under https://issues.apache.org/jira/browse/INFRA-1896

== 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 it 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.

To create the snapshot, make sure that the current directory is for a SNAPSHOT version. Perform the following command:

{{{mvn deploy -Prelease [-Dgpg.skip] [-DskipTests]}}}

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 {{{-Dgpg.skip}}} flag skips the signing phase.

The resulting snapshot will appear in the Nexus repository under:

https://repository.apache.org/content/repositories/snapshots/org/apache/commons/

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.

=== Creating a Nexus staging release ===

First, create the SVN tag (with appropriate non-SNAPSHOT version in the pom), check it out into a fresh workspace and build/test the code.
Once the code appears to be ready, the Maven artifacts can be deployed:

{{{mvn deploy -Prelease [-DskipTests]}}}

This time, the artifacts will be deployed to the release staging repository in Nexus.

To review the files that have been uploaded, login to Nexus using your Apache login and password: https://repository.apache.org/index.html
You should then see additional menu items in the LHS:
 * Enterprise
  * Staging
  * Staging Upload

Click on Enterprise/Staging and a list of your uploads should appear.
Click on the appropriate one, and it will appear below.
Click that and a listing will appear at the bottom.

Check that all the files are there (currently you can only see file names, not contents. This is a known bug.).
If OK, right-click the "open" status and select "Close" (or "Drop" if you need to try again).

Now you can right-click to download files (and drop any that should not be there e.g. .asc.md5 - if you can be bothered).
Also at this point the "Repository Path" URL becomes active to others.
This is the URL you use in the VOTE thread.
If the vote passes, right-click on the "closed" status and select "Promote" otherwise "Drop".

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org