Release Manual

1. Introduction

1.1 Apache release documentation

Refer to the following link to understand the ASF release process：

1.2 PGP signature

Follow the Apache release guidelines to sign the release version, users can also use this to determine if the downloaded version has been tampered with.

Create a pgp key for version signing, use \<your Apache ID>@apache.org as the USER-ID for the key

For more details, refer to Apache Releases Signing documentation，Cryptography with OpenPGP

Brief process for generating a key：

  • Generate a new gpg key using gpg --gen-key, set the key length to 4096 and set it to never expire
  • Upload the key to the public key server using gpg --keyserver keys.openpgp.org --send-key <your key id>
  • Export the public key to a text file using gpg --armor --export <your key id> >> gpgapachekey.txt
  • Obtain the keys of other committers for signing (optional)
  • Add the generated key to the KEYS file (uploaded to the svn repository by the release manager)

Release Manual - 图1tip

Set the default public key. If you have multiple public keys, modify ~/.gnupg/gpg.conf.

Refer to the example：

  1. [root@localhost ~]# gpg --gen-key
  2. gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
  3. ...
  4. # secret key generation directory
  5. gpg: directory `/root/.gnupg' created
  6. gpg: new configuration file `/root/.gnupg/gpg.conf' created
  7. gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run
  8. gpg: keyring `/root/.gnupg/secring.gpg' created
  9. gpg: keyring `/root/.gnupg/pubring.gpg' created
  10. Please select what kind of key you want:
  11.    (1) RSA and RSA (default)
  12.    (2) DSA and Elgamal
  13.    (3) DSA (sign only)
  14.    (4) RSA (sign only)
  15. Your selection?
  16. RSA keys may be between 1024 and 4096 bits long.
  17. What keysize do you want? (2048) 4096
  18. Requested keysize is 4096 bits
  19. Please specify how long the key should be valid.
  20.          0 = key does not expire
  21.       <n>  = key expires in n days
  22.       <n>w = key expires in n weeks
  23.       <n>m = key expires in n months
  24.       <n>y = key expires in n years
  25. Key is valid for? (0)
  26. Key does not expire at all
  27. Is this correct? (y/N) y
  29. GnuPG needs to construct a user ID to identify your key.
  30. # set USER-ID
  31. Real name: rocketmq
  32. Email address: rocketmq@apache.org
  33. Comment: rocketmq
  34. You selected this USER-ID:
  35.     "rocketmq (rocketmq) <rocketmq@apache.org>"
  37. Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
  38. You need a Passphrase to protect your secret key.
  40. ...
  41. gpg: /root/.gnupg/trustdb.gpg: trustdb created
  42. gpg: key 7DE280AF marked as ultimately trusted
  43. public and secret key created and signed.
  45. gpg: checking the trustdb
  46. gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
  47. gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
  48. pub   4096R/7DE280AF 2022-07-05
  49.       Key fingerprint = 421D C10E 9CC3 D261 9F89  C777 86BB 17AA 7DE2 80AF
  50. uid                  rocketmq (rocketmq) <rocketmq@apache.org>
  51. sub   4096R/65B9828A 2022-07-05

The generated public and private key addresses：

  1. gpg: keyring `/root/.gnupg/secring.gpg' created
  2. gpg: keyring `/root/.gnupg/pubring.gpg' created

Convert the generated public and private keys to ASCII form：

  1. gpg --armor --output /root/gpgtest/public-key.txt --export 7DE280AF
  2. gpg --armor --output /root/gpgtest/private-key.txt --export-secret-keys 7DE280AF

View the key list：

  1. [root@localhost ~]# gpg --list-keys
  2. /root/.gnupg/pubring.gpg
  3. ------------------------
  4. pub   4096R/7DE280AF 2022-07-05
  5. uid                  rocketmq (rocketmq) <rocketmq@apache.org>
  6. sub   4096R/65B9828A 2022-07-05

Upload the public key to the public key server

  1. [root@localhost gpgtest]# gpg --keyserver keys.openpgp.org --send-key 7DE280AF
  2. gpg: sending key 7DE280AF to hkp server keys.openpgp.org

1.3 POM setting

Configure the POM file to deploy the version to the ASF Nexus repository.

① Add Apache POM inheritance default settings

  1. <parent>
  2.     <groupId>org.apache</groupId>
  3.     <artifactId>apache</artifactId>
  4.     <version>XX</version>
  5. </parent>

② Add key information to the Maven configuration file settings.xml.

  1. <settings>
  2.     <profiles>
  3.         <profile>
  4.             <id>signed_release</id>
  5.             <properties>
  6.                 <mavenExecutorId>forked-path</mavenExecutorId>
  7.                 <gpg.keyname>yourKeyName</gpg.keyname>
  8.                 <deploy.url>https://dist.apache.org/repos/dist/dev/rocketmq/</deploy.url>
  9.             </properties>
  10.         </profile>
  11.     </profiles>
  12.     <servers>
  13.         <!-- To publish a snapshot of some part of Maven -->
  14.         <server>
  15.             <id>apache.snapshots.https</id>
  16.             <username>yourApacheID</username>
  17.             <!-- Use the password encryption by maven -->
  18.             <password>yourApachePassword</password>
  19.         </server>
  20.         <!-- To stage a release of some part of Maven -->
  21.         <server>
  22.             <id>apache.releases.https</id>
  23.             <username>yourApacheID</username>
  24.             <password>yourApachePassword</password>
  25.         </server>
  26.         <server>
  27.             <id>gpg.passphrase</id>
  28.             <passphrase>yourKeyPassword</passphrase>
  29.         </server>
  30.     </servers>
  31. </settings>

Release Manual - 图2tip

It is recommended to use Maven’s password encryption capabilities to encrypt gpg.passphrase.

③ Build artifacts and sign

  1. mvn clean install -Papache-release

1.4 Deal with issues

Resolve JIRA issues and GitHub issues related to this release version.

Check that MQVersion is consistent with the released version.

1.5 Release Notes

Generate Release Notes through RocketMQ JIRA and push to rocketmq-site, adding a link to the version voting email.

2. Build Source Release

Use the Maven Release plugin version release plugin to release the Artifact to the ASF Nexus staging repository, and after version validation and version voting, copy it to the Apache SVN version repository.

2.1 Check RocketMQ version

Confirm the MQVersion version and modify it to the correct form if it does not match the release-4.5.0 form or is inconsistent, and push it to the develop branch.

  1. public static final int CURRENT_VERSION = Version.V4_5_0.ordinal();

2.2 Staging in the ASF Nexus repository

  1. Switch to the develop branch and confirm that all GitHub PRs related to this version have been merged.

① Configure the pom.xml file

  1. <scm>
  2.     <url>git@github.com:apache/rocketmq.git</url>
  3.     <connection>scm:git:git@github.com:apache/rocketmq.git</connection>
  4.     <developerConnection>scm:git:git@github.com:apache/rocketmq.git</developerConnection>
  5.     <tag>rocketmq-all-x.x.x</tag>
  6. </scm>

② maven release plugin

  1. mvn release:clean
  2. mvn release:prepare
  3. mvn release:perform

Follow this process to place the generated Artifacts in the staging repository.：

  1. mvn clean release:clean: Clear failed builds and discarded versions.
  2. mvn release:prepare -Psigned_release -Darguments="-DskipTests"：Update the tag based on the SCM property.
  3. mvn -Psigned_release release:perform -Darguments="-DskipTests"：Stage the generated artifacts to the Nexus repo. You can add the -DdryRun=true parameter to perform a dry run.

After completing the above process, you can find the pre-release version Artifacts in the target directory of the local branch or in the Nexus staging repo.

Release Manual - 图3tip

To only release the source code version, only keep the source code and related jar files, and use the delete option in the Nexus GUI to delete the other artifacts.

2.3 rc version files

  • Before the pre-release version vote is passed, it will be staged in /dev/rocketmq and stored in the x.x.x-rcx/ directory. The following files are required：

    rocketmq-all-x1.x2.x3-bin-release.zip

    rocketmq-all-x1.x2.x3-bin-release.zip.asc

    rocketmq-all-x1.x2.x3-bin-release.zip.sha512

    rocketmq-all-x1.x2.x3-source-release.zip

    rocketmq-all-x1.x2.x3-source-release.zip.asc

    rocketmq-all-x1.x2.x3-source-release.zip.sha512

Generate signature and verification files using the gpg command：

  • Generate asc file

    1. gpg --clearsign rocketmq-all-x1.x2.x3-bin-release.zip
    2. gpg --clearsign rocketmq-all-x1.x2.x3-source-release.zip

  • Generate sha512 file

    1. gpg --print-md SHA512 rocketmq-all-x1.x2.x3-bin-release.zip > rocketmq-all-x1.x2.x3-bin-release.zip.sha512
    2. gpg --print-md SHA512 rocketmq-all-x1.x2.x3-source-release.zip >  rocketmq-all-x1.x2.x3-source-release.zip.sha512

Release Manual - 图4tip

The source code and binary versions should begin with rocketmq-all to facilitate the RocketMQ Docker Build.

2.4 Roll back and retry

If there are problems with the staging process, roll back according to the following process：

  • Delete the tag created in step 2.2

    • List all tags and find the most recently created one

      1. git tag -ln

    • Delete the tag from the local repository

      1. git tag -d rocketmq-all-x1.x2.x3

    • Push the update to GitHub

      1. git push origin :refs/tags/rocketmq-all-x1.x2.x3

  • Delete the commit records in the development branch from step 2.2

    • List the git log

      1. git log

    • Find the most recent commit record and label it as follows：

      des1: [maven-release-plugin] prepare release rocketmq-all-4.9.2]

      des2: [maven-release-plugin] prepare for next development iteration]

    • Delete commits

      1. git reset --hard commit-id
      2. git push origin HEAD --force

  • Delete the version to be rolled back in Nexus

  • Roll back to step 2.1 and redo

3. Build binary release

Both the binary and source code versions are built from the same code branch, but you should be aware of the operating system version.

Some dependencies, such as netty tc-native, are sensitive to the operating system.

  • Make sure you check out the pre-release version branch
  • Make sure all unit tests pass with mvn clean install
  • Make sure all integration tests pass with mvn clean install -Pit-test

After successful build, you also need to generate .asc and .sha512 files, and after verification and voting, finally copy them to the svn repository.

4. Version Verification

4.1 Binary Release Verification Checklist

  • Check the operating system for the build dependencies, netty-tcnative is sensitive to the operating system
  • Ensure the license is Apache V2
  • If third-party dependencies are introduced, update the NOTICE
  • Extract the compressed file to check that the version is correct
  • Validate the ASC signature, SHA512 digest
  • Run the Quick-Start to start the nameserver and broker
  • Run the clusterList command to check that the version is correct
  • Make sure there are no nohup.out files

4.2 Source Release Verification Checklist

  • Ensure the license is Apache V2
  • If third-party dependencies are introduced, update the NOTICE
  • Extract the compressed file to check that the version is correct
  • Validate the ASC signature, SHA512 digest
  • Compile the source code and run the Quick-Start to start the nameserver and broker
  • Run the clusterList command to check the version is correct

4.3 Verification tool

Follow the steps below to verify the GPG signature and SHA512 digest.

  1. Download the release packages, the .asc file, and the .sha512 file.

  2. On a Unix system, run the following command：

    1. for file in `find . -type f -iname '*.asc'`
    2. do
    3.     gpg --verify ${file} 
    4. done

    or

    1. gpg --verify rocketmq-all-%version-number%-source-release.zip.asc rocketmq-all-%version-number%-bin-release.zip

    If you see Good signature, the signature is correct.

    1. gpg: Good signature from ... gpg: Signature made ...

  3. Verify the consistency of the version based on the SHA512.

    1. gpg --print-md SHA512 rocketmq-all-%version-number%-source-release.zip 
    2. gpg --print-md SHA512 rocketmq-all-%version-number%-bin-release.zip

5. Close staging repo

  1. After the pre-release version has completed the checklist verification, close the Nexus staging repository and prepare for the version election.
  2. Select the orgapacherocketmq-XXX pending release version on Nexus and click the Close icon to close the staging repository.
  3. Before closing, Nexus will perform a series of signature verifications and text checks.
  4. If the verification is successful, Nexus will close the repository and provide the staging repository URL, which is marked as “The staging repo” in the election email.
  5. If the verification fails, fix the issues, roll back, and re-execute the release process.
  6. If all of the above work is complete, use SVN to copy it to the /dev/rocketmq Apache remote repository.

6. Version election

The RocketMQ community conducts version elections through the dev@rocketmq.apache.org email list.

Refer to the voting process to understand the Apache voting process.

6.1 Community voting

Email list：dev list

Email topic：[VOTE]: Release Apache RocketMQ \<release-version> RC\<RC Number>

Hello RocketMQ Community,

This is the vote for \<release version> of Apache RocketMQ.

${A brief introduction to RocketMQ and the features of this release.}

The artifacts:

https://dist.apache.org/repos/dist/dev/rocketmq/${release version}

The staging repo:

https://repository.apache.org/content/repositories/orgapacherocketmq-XXX/

Git tag for the release:

\<link to the tag of GitHub repo>

Hash for the release tag:

\<Hash value of the release tag>

Release Notes:

\<insert link to the rocketmq release notes>

The artifacts have been signed with Key : \<ID of signing key>, which can be found in the keys file:

https://dist.apache.org/repos/dist/dev/rocketmq/KEYS

The vote will be open for at least 72 hours or until necessary number of votes are reached.

Please vote accordingly:

[ ] +1 approve

[ ] +0 no opinion

[ ] -1 disapprove with the reason

Thanks,

The Apache RocketMQ Team

Release Manual - 图5tip

Hash for the release tag: You can use the commit id.

6.2 Result announced

After 72 hours, if there are at least 3 votes in favor and no votes against, send the following email to celebrate the release of the version.

Email topic：[RESULT][VOTE]: Release Apache RocketMQ \<release-version> RC\<RC Number>

Hello RocketMQ Community,

The Apache RocketMQ <release version> vote is now closed and has passed with [number] binding +1s, [number] non-binding +1s and no 0 or -1:

Binding votes +1s:

User Name (Apache ID)

User Name (Apache ID)

User Name (Apache ID)

….

Non-binding votes +1s:

User Name (Apache ID)

….

The release will be published soon.

Thanks,

The Apache RocketMQ Team

If the vote does not pass, fix the issues, roll back, increase the RC number, restart the release process, and re-initiate the version voting process.

Update email topic：[RESTART][VOTE][#]: Release Apache RocketMQ \<release-version> RC\<RC Number>

7. Release version

After the Apache RocketMQ PMC vote passes, release the version to the Maven Nexus repository and the Apache version repository.

  1. Publish to Nexus repository, select the orgapacherocketmq-XXX in the staging area and click the Release icon to publish.
  2. Publish to the Apache version repository, use SVN to copy the version to /release/rocketmq
  3. Merge the develop branch of Apache RocketMQ into the master branch.
  4. Add release notes to Releases · apache/rocketmq.
  5. Create a new branch and name it release-x.x.x.
  6. Update apache/rocketmq-site Official Website Home Page

8. Version announcement

Email list：announce@apache.org, users@rocketmq.apache.org,

​ private@rocketmq.apache.org, dev@rocketmq.apache.org

Email topic： [ANNOUNCE] Release Apache RocketMQ \<release-version>

Hi all,

The Apache RocketMQ team would like to announce the release of Apache RocketMQ \<release version>.

${A brief introduction to RocketMQ and the features of this release.}

More details regarding Apache RocketMQ can be found at:

http://rocketmq.apache.org/

The release artifacts can be downloaded here:

https://dist.apache.org/repos/dist/release/rocketmq/${release-version}

The release notes can be found here:

\<insert link to the rocketmq release notes>

Thanks,

The Apache RocketMQ Team