View source for MicroProfile/SpecRelease/Release

= How to perform a release =

== New release process ==

This new release process was prepared by John Ament (version 2). It uses a single [https://ci.eclipse.org/microprofile/view/Release/job/MicroProfile%20Releases/ MicroProfile Releases Jenkins job].

The release steps are:

# Go to [https://ci.eclipse.org/microprofile/view/Release/job/MicroProfile%20Releases/ MicroProfile Releases Jenkins job], login with your Eclipse ID, and select ''Build with Parameters''. This job builds artifacts, specification documents, and creates staging repository in Nexus.
#* Snapshot - The current development <version> identifier for your pom.xml.  For example, 2.0-SNAPSHOT
#* Release - The desired release you are attempting to build.  For example, 2.0-RC1
#* Tag - The desired tag for the release you are attempting to build.  Normally, the Tag is the same as the Release.  For example, 2.0-RC1
#* Rev - Draft or Final.  Use Draft for the RCx releases (ie. 2.0-RC1).  Use Final when doing the Final release (ie. 2.0).
#* Module - Select the repository you are attempting to build.  If your repo is not listed, you will need to modify the configuration in the [https://github.com/eclipse/microprofile-parent microprofile-parent repo].
#* Branch - Normally, you will build from "master", but some components have multiple branches (ie. 1.x-branch in the microprofile repository)
# If this is your first Jenkins build for your component, you may need to debug your configuration to get a successful build.  You may need to examine your build/console output and you may need to adjust your pom.xml to get the proper configuration.  Check out [https://github.com/eclipse/microprofile-metrics/issues/173 this githib issue] for more information on the specific updates required.  Or, reference existing working repositories like [https://github.com/eclipse/microprofile-jwt-auth microprofile-jwt-auth] or [https://github.com/eclipse/microprofile microprofile] for examples.
# Once the build succeeds...
## (recommended) Smoke test the release by building a project that depends on it. To do this, you'll need to temporarily add the staging repository for the release to that projects repositories in the pom. The staging repository URL can be found in the Sonatype Nexus Repository Manager, it will have a URL like <code>https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1126</code>, though this URL will be different for each release.
## Release the staging repository to Maven central (mandatory if a final release, recommended if non final):
##* Login to [https://oss.sonatype.org/ Sonatype].  On the left hand side, select [Staging Repositories].
##* On that tab, search for "org.eclipse.microprofile".
##* Select the appropriate staging repositories and select the "Release" action along the top action bar.
##* Leave the default action to drop the staging repositories after completing this action and click [Submit]. Once complete, it usually takes around 10 minutes (but can take longer) to sync the release across Maven Central's CDN.
## (recommended) Update the Build Information for your Jenkins job to make it more identifiable
##* DisplayName and Description
## Go to Github releases page and upload specification documents (html, pdf) and add release description.
##* Update the Release title and add suitable Description to more fully describe this release.
##* If this is a Release Candidate driver, be sure to click the box that says ``This is a pre-release``.
##* Click Publish to make the release available for reviewing.  (You can leave it in Draft state until you are happy with the presentation.)
# Announce the Release Candidate on the mailing list.
# If this is a Final release, 
## Check that your feature delivery meets the [[../../SpecChecklist | Specification Delivery Checklist]]
## Run the build with just a few updates to the above instructions. Build Parameters:
### Snapshot - The next development <version> identifier for your pom.xml.  For example, 2.1-SNAPSHOT, if you are now releasing the final 2.0 version.
### Release - The final release you are attempting to build.  For example, 2.0
### Tag - The desired tag for the final release you are attempting to build.  The Tag is the same as the Release.  For example, 2.0. If, for some reason, the final release build fails, this tag is still in use. You need to go to the corresponding repository and delete the tag, e.g. 2.0, and then kick off another release.
### Rev - Draft or Final.  Use Final when doing the Final release.
## Since this is the Final release, ensure that the ``This is a pre-release`` box is not checked when publishing the github Release.
## Announce the Final release on the mailing list and go have a beer!  


----

= Older release process (obsolete - do not use) =

This is the version 1 of the release process. It uses scripts run on a local computer manually build artifacts, push the changes to GIT and release artifacts into Maven Central. A Jenkins job per specification is used to release non-final artifacts into Eclipse maven repository instead of Maven Central. This release process is now deprecated in favor of version 2.

{{note|These instructions assume a Mac or Linux environment.  Windows is not currently supported.}}
{{note|Jump to [[#Final Release]] if you are performing a final version, e.g. 1.0}}

The following process applies to any release, including milestones, release candidates, and final release. 
# Prepare the component
## Ensure that the perform_release folder exists in the component's repo.  This folder should contain both the prepare_release.sh and deploy_to_maven_central.sh scripts.  If these are missing, copy them from the top-level [https://github.com/eclipse/microprofile-bom/blob/master/perform_release/ microprofile-bom repo].
## Ensure the component's top-level pom.xml has the appropriate &lt;scm&gt;, and release &lt;profile&gt; and &lt;plugin&gt; stanzas.  Again, compare with the top-level [https://github.com/eclipse/microprofile-bom/blob/master/pom.xml microprofile-bom pom.xml]. 
# Prepare the candidate release
## Clone the respective component repo (e.g. [https://github.com/eclipse/microprofile-bom/tree/master MicroProfile BOM master repository])
## Run the release script, which can be found under perform_release folder in the repo (e.g. [https://github.com/eclipse/microprofile-bom/blob/master/perform_release/prepare_release.sh prepare_release.sh script]).  Be sure to specify the required env vars before.  The script should create a tag (RELEASE_VERSION) and push it to the upstream repository.
##* export RELEASE_VERSION=1.0-RC1
##* export DEV_VERSION=1.0-SNAPSHOT
##* export GIT_USER='John Doe'
##* export GIT_EMAIL='john_doe@gmail.com'
# Deploy artifacts into Eclipse repository
## [https://hudson.eclipse.org/microprofile/ Logon to Jenkins] (your Eclipse logon should work)
## Go to the Jenkins release job for your component (e.g. [https://ci.eclipse.org/microprofile/job/BOM-deploy-prerelease-artifacts/ BOM-deploy-prerelease-artifacts]) and then click on "Build with Parameters"
##* If a Jenkins job does not exist for your component, then you should copy an existing job and modify according to your component.  You do that by clicking on [https://hudson.eclipse.org/microprofile/view/all/newJob New Item] on the left hand menu, and then using the "copy from" function at the bottom of that page.
# Download the PDF document from the Jenkins job (e.g. [https://ci.eclipse.org/microprofile/job/BOM-deploy-prerelease-artifacts/ws/spec/target/generated-docs/spec/target/generated-docs in the workspace]) and copy it to previously created github release page (e.g.  https://github.com/eclipse/microprofile-jwt-auth/releases/tag/1.0-RC10)  (Note:  This step could be removed if we release it to a maven repo.)
## You can also add additional text to this github release page to help explain the release.
# Notify MicroProfile community about the new version
## Send information about the created tag and artifact to review the release, e.g. on mailing-list
##* Git tag is in the [https://github.com/eclipse/microprofile-bom source repository]
##* Artifacts (API, TCK, PDF?) are in the [https://repo.eclipse.org/content/groups/microprofile/org/eclipse/microprofile/bom/ Eclipse repository]

==<span id="Final Release"></span>How to perform a release of a final version (obsolete - do not use)==

Do the steps above for a release candidate, except increase the development version instead of leaving it the same as before.

{{note|GPG utilities will be needed.  These are native on Linux.  If you are running on a Mac, consider [https://gnupg.org/download/ installing GnuPG].  Here are some good overall [https://frightanic.com/software-development/release-to-maven-central/ instructions for deploying to Maven].}}

If a release candidate is approved, it can be turned into final release.
# Run the above steps for the final version, but:
## set RELEASE_VERSION variable to the name of the final release tag (e.g. 1.0)
## increase DEV_VERSION to point to the next snapshot version (e.g. 1.1-SNAPSHOT)
# Publish the final artifact to Maven central - follow instructions in the script in the repo e.g. [https://github.com/eclipse/microprofile-bom/blob/master/perform_release/deploy_to_maven_central.sh deploy_to_maven_central.sh]
## Need to provide your ossrh userid and password in your .m2/settings.xml
## Need to provide your GPG passphrase in your .m2/settings.xml (or [https://github.com/pstadler/keybase-gpg-github/issues/11 export GPG_TTY])
## Need to provide TARGET_MAVEN_REPO setting in the deploy_to_maven_central.sh (or provide the Maven Central Staging Repository in your pom.xml)
## You may need to go [https://oss.sonatype.org/#welcome the Sonatype site] and manually Release the artifacts from the Staging repository.
# announce the final version
# increase the snapshot version in master: merge the intermediary branch branch_$RELEASE_VERSION created locally by the script to master and push master:
## git checkout master
## git merge branch_$RELEASE_VERSION
## git push origin master