Release Guide

How to publish a bRPC release

brpc apache release guide step by step

Overview: divided into the following steps

  1. Preparation: including generating the key required for signature, creating github release branch and tag, modifying the version file, etc
  2. Publish software package: including making source tarball, signing, uploading to the designated location and verifying
  3. Vote: including voting in mail group dev@brpc.apache.org and general@incubator.apache.org
  4. Release announcement: including updating brpc website, sending announcement emails, posting WeChat official account announcements, merging the release branche into the master branch

Prepare key

1. Install GPG

Download the installation package from GnuPG official website. The commands of GnuPG version 1.x and version 2.x are slightly different. The following instructions take the GnuPG-2.3.1 version (OSX) as an example.

After the installation is complete, execute the following command to check the version number.

  1. gpg --version

2. Create key

After the installation is complete, execute the following command to create a key.

  1. gpg --full-gen-key

Complete the key creation according to the prompts. Note that the mailbox should use the Apache email address, and the Real Name can use Apache ID or GitHub ID:

  1. gpg (GnuPG) 2.3.1; Copyright (C) 2021 Free Software Foundation, Inc.
  2. This is free software: you are free to change and redistribute it.
  3. There is NO WARRANTY, to the extent permitted by law.
  5. Please select what kind of key you want:
  6.    (1) RSA and RSA
  7.    (2) DSA and Elgamal
  8.    (3) DSA (sign only)
  9.    (4) RSA (sign only)
  10.    (9) ECC (sign and encrypt) *default*
  11.   (10) ECC (sign only)
  12.   (14) Existing key from card
  13. Your selection? 1
  14. RSA keys may be between 1024 and 4096 bits long.
  15. What keysize do you want? (3072) 4096
  16. Requested keysize is 4096 bits
  17. Please specify how long the key should be valid.
  18.          0 = key does not expire
  19.       <n>  = key expires in n days
  20.       <n>w = key expires in n weeks
  21.       <n>m = key expires in n months
  22.       <n>y = key expires in n years
  23. Key is valid for? (0) 0
  24. Key does not expire at all
  25. Is this correct? (y/N) y
  27. GnuPG needs to construct a user ID to identify your key.
  29. Real name: LorinLee
  30. Email address: lorinlee@apache.org
  31. Comment: lorinlee's key
  32. You selected this USER-ID:
  33.     "LorinLee (lorinlee's key) <lorinlee@apache.org>"
  35. Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
  36. You need a Passphrase to protect your secret key. # Input password
  38. We need to generate a lot of random bytes. It is a good idea to perform
  39. some other action (type on the keyboard, move the mouse, utilize the
  40. disks) during the prime generation; this gives the random number
  41. generator a better chance to gain enough entropy.
  42. gpg: key 92E18A11B6585834 marked as ultimately trusted
  43. gpg: revocation certificate stored as '/Users/lilei/.gnupg/openpgp-revocs.d/C30F211F071894258497F46392E18A11B6585834.rev'
  44. public and secret key created and signed.
  46. pub   rsa4096 2021-10-17 [SC]
  47.       C30F211F071894258497F46392E18A11B6585834
  48. uid                      LorinLee (lorinlee's key) <lorinlee@apache.org>
  49. sub   rsa4096 2021-10-17 [E]

3. Check the generated key

  1. gpg --list-keys

output:

  1. gpg: checking the trustdb
  2. gpg: marginals needed: 3  completes needed: 1  trust model: pgp
  3. gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
  4. /Users/lilei/.gnupg/pubring.kbx
  5. ----------------------------------
  6. pub   rsa4096 2021-10-17 [SC]
  7.       C30F211F071894258497F46392E18A11B6585834
  8. uid           [ultimate] LorinLee (lorinlee's key) <lorinlee@apache.org>
  9. sub   rsa4096 2021-10-17 [E]

Note that C30F211F071894258497F46392E18A11B6585834 is the public key.

4. Publish the public key to server

Execute the following command:

  1. gpg --keyserver hkp://pgp.mit.edu --send-key C30F211F071894258497F46392E18A11B6585834

5. Generate fingerprint and upload to apache user profile

Since the public key server has no verifying mechanism, anyone can upload the public key in your name, so there is no way to guarantee the reliability of the public key on the server. Usually, you can publish a public key fingerprint on your website and let others check the downloaded public key.

Execute the following command to view the fingerprint.

  1. gpg --fingerprint lorinlee # user id

output:

  1. /Users/lilei/.gnupg/pubring.kbx
  2. ----------------------------------
  3. pub   rsa4096 2021-10-17 [SC]
  4.       C30F 211F 0718 9425 8497  F463 92E1 8A11 B658 5834
  5. uid           [ultimate] LorinLee (lorinlee's key) <lorinlee@apache.org>
  6. sub   rsa4096 2021-10-17 [E]

Paste the above fingerprint C30F 211F 0718 9425 8497 F463 92E1 8A11 B658 5834 into the OpenPGP Public Key Primary Fingerprint: field of your Apache user information on https://id.apache.org.

Prepare release package

1. Create release branch

If you are releasing a new MINOR version, like 1.0.0, you need to create a new branch release-1.0 from master.

If you are releasing a new PATCH version from existing MINOR version, like 1.0.1, you only need to modify the existing release-1.0 branch and add the content to be released.

The code modification during the release process are performed on the release branch (such as release-1.0). After the release is complete, please merge the release branch back into the master branch.

2. Update version in source code

Update RELEASE_VERSION file

Edit the RELEASE_VERSION file in the project root directory, update the version number, and submit it to the code repository. For example, the 1.0.0 version of the file is:

  1. 1.0.0

Update CMakeLists.txt file

Edit the CMakeLists.txt file in the project root directory, update the version number, and submit it to the code repository. For example:

  1. set(BRPC_VERSION 1.0.0)

Update /package/rpm/brpc.spec file

Edit the /package/rpm/brpc.spec file in the project root directory, update the version number, and submit it to the code repository. For example:

  1. Version:    1.0.0

3. Create releasing tag

push the release branch to tag, For example:

  1. git clone -b release-1.0 git@github.com:apache/brpc.git ~/brpc
  3. cd ~/brpc
  5. git tag -a 1.0.0 -m "release 1.0.0"
  7. git push origin --tags

4. Create releasing package

  1. git archive --format=tar 1.0.0 --prefix=apache-brpc-1.0.0-incubating-src/ | gzip > apache-brpc-1.0.0-incubating-src.tar.gz

5. Generate GPG signature

  1. gpg -u lorinlee@apache.org --armor --output apache-brpc-1.0.0-incubating-src.tar.gz.asc --detach-sign apache-brpc-1.0.0-incubating-src.tar.gz
  3. gpg --verify apache-brpc-1.0.0-incubating-src.tar.gz.asc apache-brpc-1.0.0-incubating-src.tar.gz

6. Generate SHA512 sum

  1. sha512sum apache-brpc-1.0.0-incubating-src.tar.gz > apache-brpc-1.0.0-incubating-src.tar.gz.sha512
  3. sha512sum --check apache-brpc-1.0.0-incubating-src.tar.gz.sha512

Publish to Apache SVN repository

1. checkout dist/dev/brpc directory

If there is no local working directory, create a local working directory first. Clone the Apache SVN repository, username needs to use your own Apache LDAP username:

  1. mkdir -p ~/brpc_svn/dev/
  3. cd ~/brpc_svn/dev/
  5. svn --username=lorinlee co https://dist.apache.org/repos/dist/dev/incubator/brpc/
  7. cd ~/brpc_svn/dev/brpc

2. Add GPG public key

A new release manager must add the key into KEYS file for the first time.

  1. (gpg --list-sigs lorinlee && gpg -a --export lorinlee) >> KEYS

3. Add the releasing package to SVN directory

  1. mkdir -p ~/brpc_svn/dev/brpc/1.0.0
  3. cd ~/brpc_svn/dev/brpc/1.0.0
  5. cp ~/brpc/apache-brpc-1.0.0-incubating-src.tar.gz ~/brpc_svn/dev/brpc/1.0.0
  7. cp ~/brpc/apache-brpc-1.0.0-incubating-src.tar.gz.asc ~/brpc_svn/dev/brpc/1.0.0
  9. cp ~/brpc/apache-brpc-1.0.0-incubating-src.tar.gz.sha512 ~/brpc_svn/dev/brpc/1.0.0

4. Submit SVN

Return to the parent directory and use the Apache LDAP account to submit SVN

  1. cd ~/brpc_svn/dev/brpc
  3. svn add *
  5. svn --username=lorinlee commit -m "release 1.0.0"

Verify release

1. Verify SHA512 sum

  1. sha512sum --check apache-brpc-1.0.0-incubating-src.tar.gz.sha512

2. Verify GPG signature

First import the publisher’s public key. Import KEYS from the svn repository to the local. (The person who releases the version does not need to import it again. The person who verify needs to import it.)

  1. curl https://dist.apache.org/repos/dist/dev/incubator/brpc/KEYS >> KEYS
  3. gpg --import KEYS

Trust the signature of publisher, execute the following command using the publisher’s user name

  1. gpg --edit-key lorinlee

output:

  1. gpg (GnuPG) 2.3.1; Copyright (C) 2021 Free Software Foundation, Inc.
  2. This is free software: you are free to change and redistribute it.
  3. There is NO WARRANTY, to the extent permitted by law.
  5. Secret key is available.
  7. gpg> trust
  9. Please decide how far you trust this user to correctly verify other users' keys
  10. (by looking at passports, checking fingerprints from different sources, etc.)
  12.   1 = I don't know or won't say
  13.   2 = I do NOT trust
  14.   3 = I trust marginally
  15.   4 = I trust fully
  16.   5 = I trust ultimately
  17.   m = back to the main menu
  19. Your decision? 5
  20. Do you really want to set this key to ultimate trust? (y/N) y
  22. gpg> save

Then verify the GPG signature:

  1. gpg --verify apache-brpc-1.0.0-incubating-src.tar.gz.asc apache-brpc-1.0.0-incubating-src.tar.gz

3. Check release content

1. Compare the difference of between the source code package and github tag

  1. curl -Lo tag-1.0.0.tar.gz https://github.com/apache/brpc/archive/refs/tags/1.0.0.tar.gz
  3. tar xvzf tag-1.0.0.tar.gz
  5. tar xvzf apache-brpc-1.0.0-incubating-src.tar.gz
  7. diff -r brpc-1.0.0 apache-brpc-1.0.0-incubating-src

2. Check file content

  • Check whether the source code package contains unnecessary files, which makes the tarball too large
  • LICENSE and NOTICE files exist
  • The year in the NOTICE file is correct
  • Only text files exist, no binary files exist
  • All files have an ASF license at the beginning
  • Source code can be compiled correctly, and the unit test can pass
  • Check whether there are redundant files or folders, such as empty folders
  • Check for third-party dependency licenses:
    • Third party dependency license compatibility
    • All licenses of third-party dependency are declared in the LICENSE file
    • The complete version of the dependency license is in the license directory
    • If third-party dependency have the Apache license and have NOTICE files, these NOTICE files also need to be added to the releasing NOTICE file

Vote in Apache brpc community

1. Vote stage

  1. Send a voting email to dev@brpc.apache.org. PPMC needs to check the correctness of the version according to the document before voting. After at least 72 hours and 3 +1 PPMC member votes, you can move to the next stage.

  2. Announce the voting results and send the voting results to dev@brpc.apache.org 。

2. Vote email template

  1. Apache brpc community vote email template

Title:

  1. [VOTE] Release Apache brpc 1.0.0

Content:

Note: Release Commit ID fills in the commit ID of the last commit of the current release branch.

  1. Hi Apache brpc Community,
  3. This is a call for vote to release Apache brpc version
  4. 1.0.0
  6. [Release Note]
  7. - xxx
  9. The release candidates:
  10. https://dist.apache.org/repos/dist/dev/incubator/brpc/1.0.0/
  12. Git tag for the release:
  13. https://github.com/apache/brpc/releases/tag/1.0.0
  15. Release Commit ID:
  16. https://github.com/apache/brpc/commit/xxx
  18. Keys to verify the Release Candidate:
  19. https://dist.apache.org/repos/dist/dev/incubator/brpc/KEYS
  21. The vote will be open for at least 72 hours or until the necessary number of
  22. votes are reached.
  24. Please vote accordingly:
  25. [ ] +1 approve
  26. [ ] +0 no opinion
  27. [ ] -1 disapprove with the reason
  29. PMC vote is +1 binding, all others are +1 non-binding.
  31. Checklist for reference:
  32. [ ] Download links are valid.
  33. [ ] Checksums and PGP signatures are valid.
  34. [ ] Source code distributions have correct names matching the current
  35. release.
  36. [ ] LICENSE and NOTICE files are correct for each brpc repo.
  37. [ ] All files have license headers if necessary.
  38. [ ] No compiled archives bundled in source archive.
  40. Regards,
  41. LorinLee
  1. Apache brpc community announcement of vote result template

Title:

  1. [Result] [VOTE] Release Apache brpc 1.0.0

Content:

  1. Hi all,
  3. The vote to release Apache brpc 1.0.0 has passed.
  5. The vote PASSED with 3 binding +1, 3 non binding +1 and no -1 votes:
  7. Binding votes:
  8. - xxx
  9. - yyy 
  10. - zzz 
  12. Non-binding votes:
  13. - aaa
  14. - bbb
  15. - ccc
  17. Vote thread: xxx (vote email link in https://lists.apache.org/)
  19. Thank you to all the above members to help us to verify and vote for the 1.0.0 release. We will move to IPMC voting shortly.
  21. Regards,
  22. LorinLee

3. Vote not passed

If the community vote is not passed, please modify the code of the release branch, package and vote again.

Vote in Apache incubator community

1. Update GPG Signature

  1. svn delete https://dist.apache.org/repos/dist/release/incubator/brpc/KEYS -m "delete KEYS"
  3. svn cp https://dist.apache.org/repos/dist/dev/incubator/brpc/KEYS https://dist.apache.org/repos/dist/release/incubator/brpc/KEYS -m "update brpc KEYS"

After commit the svn, access https://downloads.apache.org/incubator/brpc/KEYS, check whether the content is updated. It may take several minutes to wait for the content to be updated before continuing.

2. Vote stage

  1. Send voting email to general@incubator.apache.org. IPMC will vote. After at least 72 hours and 3 +1 IPMC member tickets are counted, you can move to the next stage.
  2. Announce the voting results by sending the voting results to general@incubator.apache.org.

3. Vote email template

  1. Apache Incubator community vote email template

Title:

  1. [VOTE] Release Apache brpc 1.0.0

Content:

  1. Hi Incubator Community,
  3. This is a call for a vote to release Apache brpcversion
  4. 1.0.0.
  6. The Apache brpc community has voted and approved the release of Apache
  7. brpc 1.0.0.
  9. We now kindly request the Incubator PMC members review and vote on this
  10. incubator release.
  12. brpc is an industrial-grade RPC framework with extremely high performance,
  13. and it supports multiple protocols, full rpc features, and has many
  14. convenient tools.
  16. brpc community vote thread: xxx
  18. Vote result thread: xxx
  20. The release candidate:
  21. https://dist.apache.org/repos/dist/dev/incubator/brpc/1.0.0/
  23. This release has been signed with a PGP available here:
  24. https://downloads.apache.org/incubator/brpc/KEYS
  26. Git tag for the release:
  27. https://github.com/apache/brpc/releases/tag/1.0.0
  29. Build guide and get started instructions can be found at:
  30. https://brpc.apache.org/docs/getting_started
  32. The vote will be open for at least 72 hours or until the necessary number
  33. of votes is reached.
  35. Please vote accordingly:
  36. [ ] +1 approve
  37. [ ] +0 no opinion
  38. [ ] -1 disapprove with the reason
  40. Regards,
  41. Lorin Lee
  42. Apache brpc community
  1. Apache Incubator community announcement of vote result template

Title:

  1. [Result] [VOTE] Release Apache brpc 1.0.0

Content:

  1. Hi Incubator Community,
  3. Thanks to everyone that participated. The vote to release Apache
  4. brpc version 1.0.0 in general@incubator.apache.org
  5. is now closed.
  7. Vote thread: xxx
  9. The vote PASSED with 3 binding +1, 3 non binding +1 and no -1 votes:
  11. Binding votes:
  12. - xxx 
  13. - yyy 
  14. - zzz 
  16. Non-binding votes:
  17. - aaa
  18. - bbb
  19. - ccc
  21. Many thanks for all our mentors helping us with the release procedure,
  22. and all IPMC helped us to review and vote for Apache brpc release.
  23. We will proceed with publishing the approved artifacts and
  24. sending out the announcement soon.
  26. Regards,
  27. Lorin Lee
  28. Apache brpc community

Finish the release

1. Move the release package from Apache SVN directory dist/dev to dist/release

  1. svn mv https://dist.apache.org/repos/dist/dev/incubator/brpc/1.0.0 https://dist.apache.org/repos/dist/release/incubator/brpc/1.0.0 -m "release brpc 1.0.0"

2. Create github release

  1. On the GitHub Releases page Click the corresponding version of to create a new Release
  2. Edit the version number and version description, and click Publish release

3. Update download page

After waiting and confirming that the new release is synchronized to the Apache image, update the following page: https://brpc.apache.org/docs/downloadbrpc/ by change the code in https://github.com/apache/brpc-website/. Please update both Chinese and English.

The download links of GPG signature files and hash check files should use this prefix: https://downloads.apache.org/incubator/brpc/

The download link of the code package should use this prefix: https://dlcdn.apache.org/incubator/brpc/

4. Send email to announce release finished

Send mail to dev@brpc.apache.org, general@incubator.apache.org, and announce@apache.org to announce the completion of release.

Note: The email account must use personal apache email, and the email content must be plain text format (“plain text mode” can be selected in gmail). And email to announce@apache.org mail group will be delivered after manual review. Please wait patiently after sending the email, and it will be passed within one day.

The announcement email template:

Title:

  1. [ANNOUNCE] Apache brpc 1.0.0 released

Content:

Note: Brief notes of this release It is only necessary to list the main changes of this release, without corresponding contributors and PR numbers. It is recommended to refer to the previous announcement email.

  1. Hi all,
  3. The Apache brpc community is glad to announce the new release
  4. of Apache brpc 1.0.0.
  6. brpc is an Industrial-grade RPC framework using C++ Language, which is
  7. often used in high performance systems such as Search, Storage,
  8. Machine learning, Advertisement, Recommendation etc.
  10. Brief notes of this release:
  11. - xxx
  12. - yyy
  13. - zzz
  15. More details regarding Apache brpc can be found at:
  16. http://brpc.apache.org/
  18. The release is available for download at:
  19. https://brpc.apache.org/docs/downloadbrpc/
  21. The release notes can be found here:
  22. https://github.com/apache/brpc/releases/tag/1.0.0
  24. Website: http://brpc.apache.org/
  26. brpcResources:
  27. - Issue: https://github.com/apache/brpc/issues/
  28. - Mailing list: dev@brpc.apache.org
  29. - Documents: https://brpc.apache.org/docs/
  31. We would like to thank all contributors of the Apache brpc community and
  32. Incubating community who made this release possible!
  34. Best Regards,
  35. Apache brpc community

5. Publish WeChat official account announcement

Reference https://mp.weixin.qq.com/s/DeFhpAV_AYsn_Xd1ylPTSg.

6. Update master branch

After the release is completed, merge the release branch into the master branch

Last modified May 16, 2023: add security bug fix pages (#148) (a29da9f)