|
| 1 | +### Releasing |
| 2 | + |
| 3 | +In order to release to [Maven central](https://search.maven.org/), you will need [an account] (https://issues.sonatype.org) with [Sonatype OSSRH](http://central.sonatype.org/pages/ossrh-guide.html). |
| 4 | +If you do not already have an account, you can click the signup link from the login screen |
| 5 | +to begin the process of registering for an account. After signing up, you will need to add |
| 6 | +your sonatype credentials to your your maven settings file. By default this settings file is |
| 7 | +located at `$HOME/.m2/settings.xml`. In addition to sonatype credentials, you will |
| 8 | +also need to add a [gpg signing](https://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html) key configuration. |
| 9 | + |
| 10 | +For the security conscious, a [guide to encrypting credentials in maven settings files](https://maven.apache.org/guides/mini/guide-encryption.html) exists to |
| 11 | +illustrate how credentials can be protected. |
| 12 | + |
| 13 | +The following is an example settings.xml file: |
| 14 | + |
| 15 | +```xml |
| 16 | +<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" |
| 17 | + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| 18 | + xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 |
| 19 | + http://maven.apache.org/xsd/settings-1.0.0.xsd"> |
| 20 | + <profiles> |
| 21 | + <profile> |
| 22 | + <id>gpg</id> |
| 23 | + <properties> |
| 24 | + <!-- Customize the following properties to configure your gpg settings. --> |
| 25 | + <gpg.executable>gpg</gpg.executable> |
| 26 | + <gpg.keyname>keyname</gpg.keyname> |
| 27 | + <gpg.passphrase>passphrase</gpg.passphrase> |
| 28 | + <gpg.secretKeyring>${env.HOME}/.gnupg/secring.gpg</gpg.secretKeyring> |
| 29 | + </properties> |
| 30 | + </profile> |
| 31 | + </profiles> |
| 32 | + <servers> |
| 33 | + <server> |
| 34 | + <id>ossrh</id> |
| 35 | + <username>username</username> |
| 36 | + <password>password</password> |
| 37 | + </server> |
| 38 | + </servers> |
| 39 | +</settings> |
| 40 | +``` |
| 41 | + |
| 42 | +To perform a release: |
| 43 | + |
| 44 | +1. Make sure the source builds, test suites pass, and the source and java artifacts can |
| 45 | + be generated and signed: |
| 46 | +`mvn clean verify -Prelease` |
| 47 | +2. Start from a clean working directory and make sure you have no modified |
| 48 | +files in your workspace: |
| 49 | +`mvn clean && git status` |
| 50 | +3. Prepare the release: |
| 51 | +4. `mvn release:clean release:prepare` |
| 52 | +4. Enter the version to be associated with this release. |
| 53 | +You should be prompted for this version number, and the default assumed version |
| 54 | +will be shown and should correspond to the version that was in the pom.xml |
| 55 | +file but WITHOUT the `-SNAPSHOT` suffix. |
| 56 | +5. Enter the SCM tag to be used to mark this commit in the SCM. |
| 57 | +You should be prompted for this tag name, and the default will be |
| 58 | +`{projectName}-{releaseVersion}` |
| 59 | +6. Enter the new development version. |
| 60 | +You should be prompted for this version number, and the default for this will |
| 61 | +be an incremented version number of the release followed by a `-SNAPSHOT` |
| 62 | +suffix. |
| 63 | + |
| 64 | + At this point |
| 65 | + * The release plugin will continue and build/package the artifacts. |
| 66 | + * The pom.xml file will be updated to reflect the version change to the release |
| 67 | +version. |
| 68 | + * The new pom.xml will be committed. |
| 69 | + * The new commit will be tagged. |
| 70 | + * The pom.xml file will be updated again with the new development version. |
| 71 | + * Then this new pom.xml will be committed. |
| 72 | + |
| 73 | + If the process fails for some reason during any of these points, you can invoke |
| 74 | +`mvn release:rollback` to go back to the preparation point and try again, but |
| 75 | +you will also have to revert any SCM commits that were done |
| 76 | +(`git reset --hard HEAD^1` command works well for this) as well as remove any |
| 77 | +tags that were created (`git tag -l && git tag -d <tagName>` commands help |
| 78 | +with this). |
| 79 | + |
| 80 | +7. Push tags to github: |
| 81 | +`git push --follow-tags` |
| 82 | +In order for the `release:perform` goal to complete successfully, you will need to |
| 83 | +push the tags created by the maven release plugin to the remote git server. |
| 84 | + |
| 85 | +8. Perform the actual release: |
| 86 | +`mvn release:perform` |
| 87 | +A build will be performed and packaged and artifacts deployed to the sonatype |
| 88 | +staging repository. |
| 89 | + |
| 90 | +9. Log into the [Sonatype OSSHR Next](https://oss.sonatype.org) web interface |
| 91 | +to [verify and promote](http://central.sonatype.org/pages/releasing-the-deployment.html) |
| 92 | +the build. |
| 93 | + |
| 94 | +**NOTE**: By default, these instructions assumes the release is being done from a |
| 95 | +branch that can be merged into a primary branch upon successful completion, |
| 96 | +and that the SCM operations that are carried out by maven plugins will NOT |
| 97 | +access the repo, but rather, work on a local copy instead. The release plugin |
| 98 | +as configured in the maven repo sets values for this assumption |
| 99 | +(`localCheckout=true` and `pushChanges=false`). |
| 100 | + |
| 101 | +**NOTE**: If the release is being done in a separate fork of the primary |
| 102 | +github repo, doing a merge via pull request will not also copy the tags that |
| 103 | +were created during the release process. The tags will have to be created in |
| 104 | +the primary repo separately, but this may be preferred anyway. |
0 commit comments