= Release Process

This guide provides a chronological steps which goes through release tagging, staging, verification and publishing.

== Prerequisites

You need to make sure you have access to the JBoss nexus server, with permissions to stage, and release.  The documents above have information on this, but if you are not sure please contact JBoss helpdesk, and follow up with the project lead.

=== Release settings

Before beginning any of the procedures below you need to setup your maven installation.

Use following template for a `release-settings.xml` and pass it to all Maven executions (just change `username`, `password` and `localRepository` settings as convenient):

[source,xml]
----
<settings>
    <localRepository>/tmp/richfaces-release-localRepository</localRepository>

    <mirrors>
        <mirror> 
            <id>jboss-staging-repository-group</id> 
            <mirrorOf>*,!jboss-qa-releases-repository</mirrorOf> 
            <name>JBoss.org Staging Repository Group</name> 
            <url>https://repository.jboss.org/nexus/content/groups/staging</url> 
        </mirror>
    </mirrors>

    <servers>
        <server>
            <id>jboss-releases-repository</id>
            <username>{your_email}</username>
            <password>{your_password}</password>
        </server>
    </servers>

</settings>
----

Using these settings you will use separated local repository which will be popullated only with artifacts from JBoss Staging repository and released artifacts. That way you can verify that the build is reproducible using JBoss Maven repositories.

=== Environment

|===
| Maven | 3.0.4

| JDK | OpenJDK 1.7

| MAVEN_OPTS | -Xmx1024m -XX:MaxPermSize=512m
|===

=== Update RichWidgets Tag

RichFaces depends on RichWidgets bower dependency in a `framework/src/main/js`.

During development, it depends on `#dist` as a continous integration branch,
but in a release, we need to switch to a tagged version (e.g. `#0.2`).

1. update the tag
1. follow instructions in `framework/src/main/js/README` to update RichWidgets resources in the project
1. commit the updated `bower.json` and copied resources


=== Notify Development Team

Also the person performing any of the releases below should also post a message to the RichFaces developer forum stating:

____
The release process for <5.0.0.Alpha1> is about to begin. Further commits into develop branch will not be considered in release.
____

When the release is completed be sure to post to the forums again.

=== Review Issue Tracker Status and Continuous Integration

Before starting any release steps, make sure the CI tests pass and that all issues scheduled to particular version are resolved.

=== Finish Release Notes

`dist/src/main/resources/txt/release-notes.txt` should be updated before starting with release (you can use the raw output of JIRA's Release Notes for particular version.


== Release Tag Preparation

First, you need to diverge a release branch:

----
git checkout master -b release/5.0.0.Alpha1
----

In order to verify that build pass, you should execute dry run:

----
mvn -s <release-settings.xml> -Prelease clean verify
----

Once the build pass, you can start to prepare a release (prepare and tag a version):

----
mvn -s <release-settings.xml> --batch-mode -Dtag=<5.0.0.Alpha1> -DreleaseVersion=<5.0.0.Alpha1> -DdevelopmentVersion=<5.0.0-SNAPSHOT> release:prepare 
----

This will change a current snapshot version in all POMs and other regular files to a release version (`5.0.0.Alpha1`). The sources will be tagged (`5.0.0.Alpha1`) and then the version will be changed back to next development version (`5.0.0-SNAPSHOT`).

You can push the release branch to the repository at this stage:

----
git push origin release/5.0.0.Alpha1
----

== Release Staging

The release is now prepared for staging to the JBoss Maven repository:

---- 
mvn -s <release-settings.xml> --batch-mode -Dtag=<5.0.0.Alpha1> -DreleaseVersion=<5.0.0.Alpha1> -DdevelopmentVersion=<5.0.0-SNAPSHOT> release:perform
----

This will build from the tag, and perform the actual uploads to the JBoss staging repo.
For this step, you need to be properly authenticated (see `release-settings.xml`).

If there are issues with staging you need to "Drop" whatever was already staged in a JBoss Nexus administration interface (see https://community.jboss.org/wiki/MavenDeployingARelease[Maven Deploying a Release] for details).

If everything went fine, you can "Close" the release and make it available for release verification. Use comment "RichFaces 5.0.0.Alpha1" release in a message for closing a staging repository (see https://community.jboss.org/wiki/MavenDeployingARelease[Maven Deploying a Release] for details).

If QE and development find issues, and the release needs to be dropped follow the directions above, and "drop" the staging repository.

=== Push Tag

Once the release staging is performed, you can push the tag to the repository:

----
git push origin 5.0.0.Alpha1
----

== Release Verification

At this point the staged release is prepared for verification by QE.

Update details about the release to the RFPL JIRA for this release:

----
RichFaces version: {{5.0.0.Alpha1}}
RichFaces tag: [{{5.0.0.Alpha1}}|https://github.com/richfaces/richfaces5/commits/5.0.0.Alpha1]
Metamer tag: {{???}}
Shared Stage: https://repository.jboss.org/nexus/content/groups/staging/
Private stage: https://repository.jboss.org/nexus/content/repositories/jboss_releases_staging_profile-061/


*Release Notes:*

https://issues.jboss.org/secure/ReleaseNote.jspa?projectId=12310341&version=12320296
----


== Releasing/Dropping

Once QE and development have verified and cleared the staged release following the release testing process, next step is to promote the staged bits to JBoss maven release repo.
 
This is very easy.  Simply log into the nexus server following https://community.jboss.org/docs/DOC-15179[Maven Deploying a Release] and "promote" the release.
 
If QE and development find issues, and the release needs to be dropped follow the directions above, and "drop" the stage.


== Merging Release branch with Master branch

At this point, you can merge a release branch back to the master branch:

----
git fetch origin
git checkout master
git rebase origin/master
git merge release/5.0.0.Alpha1
----

Since the version of `master` and `release/5.0.0.Alpha1` are now same, there should be rarely some merging conflicts.

Resolve potential conflicts and verify a build:

----
mvn clean verify
----

Now you can push the merged release branch to master and then remove the release branch:

----
git push origin master
git push origin :release/5.0.0.Alpha1
----
