Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "MicroProfile/SpecRelease/Release"

(Standard Release process under MicroProfile Working Group)
(Plan Review)
(26 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
= How to perform a release =
 
= How to perform a release =
 +
 +
== Plan Review ==
 +
Any major or minor release must first perform a plan review.
 +
# A [https://projects.eclipse.org/projects/technology.microprofile spec plan review] has been created for each new or update spec, which lists the updated or new features in this release.
 +
# The spec team contacts a MicroProfile Working Group memeber to start a ballot (detailed below). Alternatively, send an email to microprofile-wg@eclipse.org to ask for a volunteer.
 +
## (Steering Committee Member) Send an email to MicroProfile WG to initiate the ballot on plan review. The ballot lasts for 7 days. After 7 days elapses, if the super majority vote +1, the ballot will be concluded successfully.
 +
## After the ballot is concluded the result will be posted to microprofile-wg mailing list.
  
 
== Pre-Release Review Steps ==
 
== Pre-Release Review Steps ==
Line 9: Line 16:
 
#* Verify pom.xml has been updated with new spec dependencies (when a new specification is added). Spec teams should provide this, but worth the double-check.  
 
#* Verify pom.xml has been updated with new spec dependencies (when a new specification is added). Spec teams should provide this, but worth the double-check.  
 
#* Verify pom.xml has updated spec version numbers in the properties section. Spec teams should update this, but worth the double-check.  
 
#* Verify pom.xml has updated spec version numbers in the properties section. Spec teams should update this, but worth the double-check.  
#* Verify architecture.adoc and required-apis.adoc updated with new specs and updated version numbers
+
#* Verify architecture.adoc is updated with new specs and updated version numbers
 +
#* Verify required-apis.adoc is updated with new specs and updated version numbers
 
#* Verify README.adoc is up-to-date with example POM file version number and any other spec changes.
 
#* Verify README.adoc is up-to-date with example POM file version number and any other spec changes.
#* Verify copyright dates have been updated in all files that mention these.
+
#* Verify copyright dates have been updated in all ''changed'' files that mention these.
 
#* Verify spec release pages contain a release text including incompatible changes and feature changes, linking to the "Changelog" section at a minimum.
 
#* Verify spec release pages contain a release text including incompatible changes and feature changes, linking to the "Changelog" section at a minimum.
 
# Test build locally
 
# Test build locally
#* [https://github.com/eclipse/microprofile MicroProfile Clone the project] and build locally before executing a release  (mvn clean install)
+
#* [https://github.com/eclipse/microprofile MicroProfile Clone the project] and build locally before executing a release  (mvn clean verify)
#* Look at log output. Even without errors, there may be warnings (improper javadoc annotations, etc). Notify spec teams by logging a GitHub issue on that project and, if time-sensitive, contacting directly. A CR (candidate release) will catch these early so they will not be as time-sensitive.
+
#* Look at log output. Even without errors, there may be warnings (improper javadoc annotations, etc). Notify spec teams by logging a GitHub issue on that project and, if time-sensitive, contacting directly. A RC (release candidate) will catch these early so they will not be as time-sensitive.
 
#* Verify proper MP spec PDF and HTML have been generated.
 
#* Verify proper MP spec PDF and HTML have been generated.
 
+
# Platform releases require that the Marketing committee be notified at least two weeks in advance. This will kick off microprofile.io site updates, updated presentation, etc. This is done by opening a [https://github.com/eclipse/microprofile-marketing/issues marketing GitHub issue] noting the release date. If major/minor updates to component specifications include notable features, it is optional to create a marketing issue so tweets can be published to notify the community.
 
+
Platform releases require that the Marketing committee be notified at least two weeks in advance. This will kick off microprofile.io site updates, updated presentation, etc. This is done by opening a [https://github.com/eclipse/microprofile-marketing/issues marketing GitHub issue] noting the release date. If major/minor updates to component specifications include notable features, it is optional to create a marketing issue so tweets can be published to notify the community.
+
  
 
==Standard Release process under MicroProfile Working Group==
 
==Standard Release process under MicroProfile Working Group==
Line 25: Line 31:
 
#Ensure to create a Release Notes section on the spec by following this [https://wiki.eclipse.org/MicroProfile/ReleaseNotes instruction]
 
#Ensure to create a Release Notes section on the spec by following this [https://wiki.eclipse.org/MicroProfile/ReleaseNotes instruction]
  
===Milestone or Release Candidates Releases===
+
===Milestone or Release Candidates or Micro Release ===
  
 
#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.  
 
#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.  
Line 34: Line 40:
 
#* 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].
 
#* 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)
 
#* 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.
+
#* StagingList - A comma-separated list of the staging URLs from which you would like to pull artifacts during the build
 +
## Example: https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1384/,https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1385/
 +
# 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. If the build fails but the tag and release commits have been pushed to GitHub you will need to delete the created tag and remove the release commits (force push) before running the release job again.
 
# Once the build succeeds...
 
# 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.
 
## (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.
Line 44: Line 52:
 
## (recommended) Update the Build Information for your Jenkins job to make it more identifiable
 
## (recommended) Update the Build Information for your Jenkins job to make it more identifiable
 
##* DisplayName and Description
 
##* DisplayName and Description
 +
## Post Release proces. Go to [https://ci.eclipse.org/microprofile/view/Release/job/MicroProfile%20Post-Release/ MicroProfile Releases Jenkins job], login with your Eclipse ID, and select ''Build with Parameters''. This job moves the release artifacts from staging dir https://download.eclipse.org/microprofile/staging/ to microprofile dir (https://download.eclipse.org/microprofile/).
 +
##* Release - The release you have built in the previous step.  For example, 2.0-RC1
 +
##* 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].
 
## Go to Github releases page and add links to javadoc, specification documents (html, pdf) and add release description (click [https://github.com/eclipse/microprofile-fault-tolerance/releases here] for an example. All release artificates are listed [https://download.eclipse.org/microprofile/ here]).
 
## Go to Github releases page and add links to javadoc, specification documents (html, pdf) and add release description (click [https://github.com/eclipse/microprofile-fault-tolerance/releases here] for an example. All release artificates are listed [https://download.eclipse.org/microprofile/ here]).
 
##* Update the Release title and add suitable Description to more fully describe this release.
 
##* Update the Release title and add suitable Description to more fully describe this release.
Line 49: Line 60:
 
##* Click Publish to make the release available for reviewing.  (You can leave it in Draft state until you are happy with the presentation.)
 
##* 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 [https://groups.google.com/forum/#!forum/microprofile mailing list].
 
# Announce the Release Candidate on the [https://groups.google.com/forum/#!forum/microprofile mailing list].
 +
# If this is the platform release, you need to engage marketing team by following [https://github.com/eclipse/microprofile-marketing/wiki/Marketing-Release-Process] procedure.
  
===Final Releases===
+
===Major or Minor Final Releases===
  
 
You must follow the following steps defined by MicroProfile Working Group to perform a final release
 
You must follow the following steps defined by MicroProfile Working Group to perform a final release
Line 59: Line 71:
 
#* 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.
 
#* 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.
 
#* 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.
+
#* StagingList - A comma-separated list of the staging URLs from which you would like to pull artifacts during the build
 +
## Example: https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1384/,https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1385/
 
# Once the build succeeds...
 
# 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.
 
## (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.
 
##* Login to [https://oss.sonatype.org/ Sonatype].  On the left hand side, select [Staging Repositories].
 
##* Login to [https://oss.sonatype.org/ Sonatype].  On the left hand side, select [Staging Repositories].
 
##* On that tab, search for "org.eclipse.microprofile".
 
##* On that tab, search for "org.eclipse.microprofile".
## Note down the staging url for the final release and fill in the details on the issue you created on microprofile-wg.
+
## (recommended) Update the Build Information for your Jenkins job to make it more identifiable
## Create a Compatible Implementation Issue on the corresponding MicroProfile repo to log the details with the proof of using the staged API, TCK jars and all TCKs passed (e.g. [https://github.com/eclipse/microprofile-config/issues/656 config 2.0 CCR]
+
##* DisplayName and Description
## Verify the release date on the Component Release Record created earlier is at least two weeks away to give Eclipse Foundation sufficient time to carray out IP and other checks.
+
## Note down the staging url for the final release and then use these info to fill in the details on the issue you created on microprofile-wg.
## Follow the instruction on the Specification Review issue to send email to PMC for PMC approval. You normally can get approval with 1-2 days.
+
## Create a Compatible Implementation Issue on the corresponding MicroProfile repo to log the details with the proof of using the staged API, TCK jars and all TCKs passed (e.g. [https://github.com/eclipse/microprofile-config/issues/656 config 2.0 CCR])
## Follow the instruction on the Specification Review issue to send email to EMO for EMO approval. After an email is sent, a bug zilla will be created to track the release. You need to add the bugzilla link to the Specification Review issue. This step normally takes longer. It will asks for IP logs. You need to generate IP Logs from the same site where you create Component Release Record. For MicroProfile specifications, if a few specs are released at the same time, the first spec that goes into EMO process will have the IP log generated and the IP log will cover the rest specifications as MicroProfile specs share one single project. After IP log is approved, EMO will wait for MicroProfile WG ballot to conclude before a final review is approved.
+
## Verify the release date on the Component Release Record created earlier for being at least two weeks away, as you need to give Eclipse Foundation sufficient time to carray out IP and other checks.
## Follow the instruction on the Specification Review issue to send email to MicroProfile WG to initiate the ballot. The ballot lasts for 14 days but it can exit after 7 days if all of the corporate members have voted. After 14 days elapses, if the super majority vote +1, the ballot will be concluded as a success.  
+
## Follow the instruction on the Specification Review issue to send an email to PMC for PMC approval. You normally can get an approval with 1-2 days. If you are not already a member of the technology-pmc and microprofile-wg mailing lists, [https://accounts.eclipse.org/mailing-list/ sign up] to avoid having your emails bounce.
## After the ballot is concluded and the result will be posted to microprofile-wg mailing list.
+
## Follow the instruction on the Specification Review issue to send an email to EMO for EMO approval. After an email is sent, a bug zilla will be created to track the release. You need to add the bugzilla link to the Specification Review issue. EMO approval normally takes longer time. It will asks for IP logs. If you need to generate IP Logs, just log onto the same site where you create Component Release Record and then click `Generate IP Log` on the right hand side. For MicroProfile specifications, if a number of specs are released at the same time, the first spec that goes into EMO process will have the IP log generated and the IP log will cover the rest specifications, because all of the MicroProfile specs share one single project. After IP log is approved, EMO will wait for MicroProfile WG ballot to conclude successfully (see the next bulletin list) before a final review is approved.
 +
## (Steering Committee Member) After the CCR has been completed, follow the instruction on the Specification Review issue to send an email to MicroProfile WG to initiate the ballot. The ballot lasts for 14 days but it can exit after 7 days if all of the corporate members have voted. After 14 days elapses, if the super majority vote +1, the ballot will be concluded successfully.  
 +
## After the ballot is concluded the result will be posted to microprofile-wg mailing list.
 
## EMO will approve the release on the date mentioned on the bugzilla.
 
## EMO will approve the release on the date mentioned on the bugzilla.
 
## Once EMO approves, you can then log back to Sonatype and click on `Release` button to release the artifacts to Maven central.
 
## Once EMO approves, you can then log back to Sonatype and click on `Release` button to release the artifacts to Maven central.
## You can send an email to microprofile mailing list to announce the release and update the release tag in the corresponding github repo with all of the links to spec pdf/html/javadoc.
+
## Post Release proces. Go to [https://ci.eclipse.org/microprofile/view/Release/job/MicroProfile%20Post-Release/ MicroProfile Releases Jenkins job], login with your Eclipse ID, and select ''Build with Parameters''. This job moves the release artifacts from staging dir https://download.eclipse.org/microprofile/staging/ to microprofile dir (https://download.eclipse.org/microprofile/).  
## Tweet about it!
+
##* Release - The release you have built in the previous step.  For example, 2.0
## After the build finishes, you need to log onto sona
+
##* 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].
 
+
== Previous 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:
+
 
+
#Update MicroProfile calendar with required dates.  (More info coming...)
+
#Ensure to create a Release Notes section on the spec by following this [https://wiki.eclipse.org/MicroProfile/ReleaseNotes instruction]
+
#Get 3rd dependency CQs approved by following the [https://wiki.eclipse.org/MicroProfile/3rdPartyDependencyProcess dependency process]
+
#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. '''For a final release, please skip to the "Final Release" step below.'''
+
#* 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 add links to javadoc, specification documents (html, pdf) and add release description (click [https://github.com/eclipse/microprofile-fault-tolerance/releases here] for an example. All release artificates are listed [https://download.eclipse.org/microprofile/ here]).
 
## Go to Github releases page and add links to javadoc, specification documents (html, pdf) and add release description (click [https://github.com/eclipse/microprofile-fault-tolerance/releases here] for an example. All release artificates are listed [https://download.eclipse.org/microprofile/ here]).
 
##* Update the Release title and add suitable Description to more fully describe this release.
 
##* 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.)
 
##* 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 [https://groups.google.com/forum/#!forum/microprofile mailing list].
+
## Get in touch with Marketing to engage on the exposure being prepared for this release
# If this is a Final release, just a few updates/additions 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.
+
## Release the Sonatype Staging Repo to make the final release available in Maven.
+
## Update MicroProfile Impl page:  https://wiki.eclipse.org/MicroProfile/Implementation
+
## Update MicroProfile Downloads page:  https://projects.eclipse.org/projects/technology.microprofile/downloads
+
## Tweet about it!
+
## Announce the Final release on the [https://groups.google.com/forum/#!forum/microprofile mailing list] and go have a beer!
+
 
+
== Troubleshooting ==
+
 
+
* In the event that the build portion of the Jenkins task succeeds, but fails to publish to Sonatype - for example, the Jenkins build may fail with a "Gateway Timeout" - this may leave the repository in an inconsistent state.  The release tooling will likely have created a new commit for the release and tagged the branch.  Once the branch is tagged, then it is not possible to run through the release tooling again with the same tag.  The following steps should help resolve this issue:
+
*# Log into [https://oss.sonatype.org/ Sonatype] and look for your (botched) release under [Staging Repositories].  If it exists, [Drop] it.
+
*# Next, proceed to your project repository in GitHub, then navigate to the [Code] tab, then the [releases] sub-tab.  If the botched release exists there, you can delete it by clicking on the release name, and then clicking the [Delete] button.  Likewise, click on the [Tags] button and similarly delete the tag.
+
*# You will need to add a commit to the repository before the release tooling will create a new release.  If there is a typo in the javadoc, this is a great opportunity to fix it. :)
+
*# Now you should be ready to restart the release process above - and hopefully you'll have better luck this time.
+
 
+
----
+
 
+
= 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
+

Revision as of 08:53, 16 June 2022

How to perform a release

Plan Review

Any major or minor release must first perform a plan review.

  1. A spec plan review has been created for each new or update spec, which lists the updated or new features in this release.
  2. The spec team contacts a MicroProfile Working Group memeber to start a ballot (detailed below). Alternatively, send an email to microprofile-wg@eclipse.org to ask for a volunteer.
    1. (Steering Committee Member) Send an email to MicroProfile WG to initiate the ballot on plan review. The ballot lasts for 7 days. After 7 days elapses, if the super majority vote +1, the ballot will be concluded successfully.
    2. After the ballot is concluded the result will be posted to microprofile-wg mailing list.

Pre-Release Review Steps

  1. Spec release creation
    • Verify a spec release has been created for each new or update spec.
    • For missing spec releases, notify spec teams by logging a github issue on that project and, if time-sensitive, contacting directly.
  2. In MicroProfile project source
    • NOTE: The build process will update the pom.xml <version>X.Y-SNAPSHOT</version> tags automatically, so do not manually change these.
    • Verify pom.xml has been updated with new spec dependencies (when a new specification is added). Spec teams should provide this, but worth the double-check.
    • Verify pom.xml has updated spec version numbers in the properties section. Spec teams should update this, but worth the double-check.
    • Verify architecture.adoc is updated with new specs and updated version numbers
    • Verify required-apis.adoc is updated with new specs and updated version numbers
    • Verify README.adoc is up-to-date with example POM file version number and any other spec changes.
    • Verify copyright dates have been updated in all changed files that mention these.
    • Verify spec release pages contain a release text including incompatible changes and feature changes, linking to the "Changelog" section at a minimum.
  3. Test build locally
    • MicroProfile Clone the project and build locally before executing a release (mvn clean verify)
    • Look at log output. Even without errors, there may be warnings (improper javadoc annotations, etc). Notify spec teams by logging a GitHub issue on that project and, if time-sensitive, contacting directly. A RC (release candidate) will catch these early so they will not be as time-sensitive.
    • Verify proper MP spec PDF and HTML have been generated.
  4. Platform releases require that the Marketing committee be notified at least two weeks in advance. This will kick off microprofile.io site updates, updated presentation, etc. This is done by opening a marketing GitHub issue noting the release date. If major/minor updates to component specifications include notable features, it is optional to create a marketing issue so tweets can be published to notify the community.

Standard Release process under MicroProfile Working Group

  1. Create Component Release Record to document what release you are planning to perform (See here for Config 2.0 Release Record)
  2. Ensure to create a Release Notes section on the spec by following this instruction

Milestone or Release Candidates or Micro Release

  1. Go to 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 microprofile-parent repo.
    • Branch - Normally, you will build from "master", but some components have multiple branches (ie. 1.x-branch in the microprofile repository)
    • StagingList - A comma-separated list of the staging URLs from which you would like to pull artifacts during the build
    1. Example: https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1384/,https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1385/
  2. 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 this githib issue for more information on the specific updates required. Or, reference existing working repositories like microprofile-jwt-auth or microprofile for examples. If the build fails but the tag and release commits have been pushed to GitHub you will need to delete the created tag and remove the release commits (force push) before running the release job again.
  3. Once the build succeeds...
    1. (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 https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1126, though this URL will be different for each release.
    2. Release the staging repository to Maven central
      • Login to 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.
    3. (recommended) Update the Build Information for your Jenkins job to make it more identifiable
      • DisplayName and Description
    4. Post Release proces. Go to MicroProfile Releases Jenkins job, login with your Eclipse ID, and select Build with Parameters. This job moves the release artifacts from staging dir https://download.eclipse.org/microprofile/staging/ to microprofile dir (https://download.eclipse.org/microprofile/).
      • Release - The release you have built in the previous step. For example, 2.0-RC1
      • Module - Select the repository you are attempting to build. If your repo is not listed, you will need to modify the configuration in the microprofile-parent repo.
    5. Go to Github releases page and add links to javadoc, specification documents (html, pdf) and add release description (click here for an example. All release artificates are listed here).
      • 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.)
  4. Announce the Release Candidate on the mailing list.
  5. If this is the platform release, you need to engage marketing team by following [1] procedure.

Major or Minor Final Releases

You must follow the following steps defined by MicroProfile Working Group to perform a final release

  1. Create a Release Review issue under microprofile-wg using the template of `Specification Review Issue (e.g. MicroProfile Config 2.0 Specification Review).
  2. Kick off a Jenkins build with the following 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.
    • StagingList - A comma-separated list of the staging URLs from which you would like to pull artifacts during the build
    1. Example: https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1384/,https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1385/
  3. Once the build succeeds...
    1. (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 https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1126, though this URL will be different for each release.
      • Login to Sonatype. On the left hand side, select [Staging Repositories].
      • On that tab, search for "org.eclipse.microprofile".
    2. (recommended) Update the Build Information for your Jenkins job to make it more identifiable
      • DisplayName and Description
    3. Note down the staging url for the final release and then use these info to fill in the details on the issue you created on microprofile-wg.
    4. Create a Compatible Implementation Issue on the corresponding MicroProfile repo to log the details with the proof of using the staged API, TCK jars and all TCKs passed (e.g. config 2.0 CCR)
    5. Verify the release date on the Component Release Record created earlier for being at least two weeks away, as you need to give Eclipse Foundation sufficient time to carray out IP and other checks.
    6. Follow the instruction on the Specification Review issue to send an email to PMC for PMC approval. You normally can get an approval with 1-2 days. If you are not already a member of the technology-pmc and microprofile-wg mailing lists, sign up to avoid having your emails bounce.
    7. Follow the instruction on the Specification Review issue to send an email to EMO for EMO approval. After an email is sent, a bug zilla will be created to track the release. You need to add the bugzilla link to the Specification Review issue. EMO approval normally takes longer time. It will asks for IP logs. If you need to generate IP Logs, just log onto the same site where you create Component Release Record and then click `Generate IP Log` on the right hand side. For MicroProfile specifications, if a number of specs are released at the same time, the first spec that goes into EMO process will have the IP log generated and the IP log will cover the rest specifications, because all of the MicroProfile specs share one single project. After IP log is approved, EMO will wait for MicroProfile WG ballot to conclude successfully (see the next bulletin list) before a final review is approved.
    8. (Steering Committee Member) After the CCR has been completed, follow the instruction on the Specification Review issue to send an email to MicroProfile WG to initiate the ballot. The ballot lasts for 14 days but it can exit after 7 days if all of the corporate members have voted. After 14 days elapses, if the super majority vote +1, the ballot will be concluded successfully.
    9. After the ballot is concluded the result will be posted to microprofile-wg mailing list.
    10. EMO will approve the release on the date mentioned on the bugzilla.
    11. Once EMO approves, you can then log back to Sonatype and click on `Release` button to release the artifacts to Maven central.
    12. Post Release proces. Go to MicroProfile Releases Jenkins job, login with your Eclipse ID, and select Build with Parameters. This job moves the release artifacts from staging dir https://download.eclipse.org/microprofile/staging/ to microprofile dir (https://download.eclipse.org/microprofile/).
      • Release - The release you have built in the previous step. For example, 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 microprofile-parent repo.
    13. Go to Github releases page and add links to javadoc, specification documents (html, pdf) and add release description (click here for an example. All release artificates are listed here).
      • Update the Release title and add suitable Description to more fully describe this release.
      • Click Publish to make the release available for reviewing. (You can leave it in Draft state until you are happy with the presentation.)
    14. Get in touch with Marketing to engage on the exposure being prepared for this release

Back to the top