Release指南

如何发布一个bRPC Release版本

brpc 发布apache release 版本流程step by step

概述：分为如下几个步骤

  1. 事前准备：包括生成签名需要的key，github拉取发布分支、打tag，修改version文件等
  2. 发布软件包：包括制作source tarball，签名，上传到制定地点并验证
  3. 投票：包括在dev@brpc邮件群里投票，以及在general@incubator.apache.org邮件群里投票
  4. 发版通告：包括更新brpc网站，发邮件，发微信公众号公告，合并发布分支到master分支

签名准备

1. 安装 GPG

在GnuPG官网下载安装包。 GnuPG的1.x版本和2.x版本的命令有细微差别，下列说明以GnuPG-2.3.1版本（OSX）为例。

安装完成后，执行以下命令查看版本号。

  1. gpg --version

2. 创建 key

安装完成后，执行以下命令创建key。

  1. gpg --full-gen-key

根据提示完成创建key，注意邮箱要使用Apache邮件地址，Real Name使用姓名Pinyin、Apache ID或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. # 输入密码
  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. 查看生成的key

  1. gpg --list-keys

执行结果：

  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]

其中 C30F211F071894258497F46392E18A11B6585834 为公钥ID。

4. 将公钥公布到服务器

命令如下：

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

5. 生成 fingerprint 并上传到 apache 用户信息中

由于公钥服务器没有检查机制，任何人都可以用你的名义上传公钥，所以没有办法保证服务器上的公钥的可靠性。通常，你可以在⽹站上公布一个公钥指纹，让其他⼈核对下载到的公钥是否为真。fingerprint参数生成公钥指纹。

执行如下命令查看 fingerprint：

  1. gpg --fingerprint lorinlee（用户ID）

输出如下：

  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]

将上面的 fingerprint C30F 211F 0718 9425 8497 F463 92E1 8A11 B658 5834 粘贴到⾃己Apache⽤户信息 https://id.apache.org 的OpenPGP Public Key Primary Fingerprint:字段中。

发布包准备

1. 拉出发版分支

如果是发布新的2位版本，如1.0.0，则需要从master拉出新的分支release-1.0。

如果是在已有的2位版本上发布新的3位版本，如1.0.1版本，则只需要在已有的release-1.0分支上修改加上要发布的内容。

发版过程中的操作都在release分支（如release-1.0）上操作，如果发版过程发现代码有问题需要修改，也在该分支上进行修改。发版完成后，将该分支合回master分支。

2. 编辑 RELEASE_VERSION 文件

更新RELEASE_VERSION文件

编辑项目根目录下RELEASE_VERSION文件，更新版本号，并提交至代码仓库，本文以1.0.0版本为例，文件内容为：

  1. 1.0.0

更新CMakeLists.txt文件

编辑项目根目录下CMakeLists.txt文件，更新版本号，并提交至代码仓库，本文以1.0.0版本为例，修改BRPC_VERSION为：

  1. set(BRPC_VERSION 1.0.0)

更新/package/rpm/brpc.spec文件

编辑项目根目录下/package/rpm/brpc.spec文件，更新版本号，并提交至代码仓库，本文以1.0.0版本为例，修改Version为：

  1. Version:    1.0.0

3. 创建发布 tag

拉取发布分支，并推送tag

  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. 打包发布包

  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. 生成签名文件

  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. 生成哈希文件

  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

发布至Apache SVN仓库

1. 检出 dist/dev 下的 brpc 仓库目录

如无本地工作目录，则先创建本地工作目录。将Apache SVN仓库克隆下来，username需要使用自己的Apache LDAP用户名

  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. 添加GPG公钥

仅第一次部署的账号需要添加，只要KEYS中包含已经部署过的账户的公钥即可。

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

3. 将待发布的代码包添加至SVN目录

  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. 提交SVN

退回到上级目录，使用Apache LDAP账号提交SVN

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

检查发布结果

1. 检查sha512哈希

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

2. 检查GPG签名

首先导入发布人公钥。从svn仓库导入KEYS到本地环境。（发布版本的人不需要再导入，帮助做验证的人需要导入，用户名填发版人的即可）

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

设置信任该用户的签名，执行以下命令，填写发布人的用户名

  1. gpg --edit-key lorinlee

输出为

  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

然后进行gpg签名检查。

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

3. 检查发布内容

1. 对比源码包与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. 检查源码包的文件内容

  • 检查源码包是否包含由于包含不必要文件，致使tarball过于庞大
  • 存在LICENSE和NOTICE文件
  • NOTICE文件中的年份正确
  • 只存在文本文件，不存在二进制文件
  • 所有文件的开头都有ASF许可证
  • 能够正确编译，单元测试可以通过
  • 检查是否有多余文件或文件夹，例如空文件夹等
  • 检查第三方依赖许可证：
    • 第三方依赖的许可证兼容
    • 所有第三方依赖的许可证都在LICENSE文件中声名
    • 依赖许可证的完整版全部在license目录
    • 如果依赖的是Apache许可证并且存在NOTICE文件，那么这些NOTICE文件也需要加入到版本的NOTICE文件中

在Apache brpc社区发起投票

1. 投票阶段

  1. 发起投票邮件到dev@brpc.apache.org。PPMC需要先按文档检查版本的正确性，然后再进行投票。经过至少72小时并统计到3个+1 PPMC member票后，即可进入下一阶段。
  2. 宣布投票结果，发起投票结果邮件到dev@brpc.apache.org。

2. 投票邮件模板

  1. Apache brpc 社区投票邮件模板

标题：

  1. [VOTE] Release Apache brpc 1.0.0

正文：
注：Release Commit ID填写当前release发版分支最后一个commit的commit id。

  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 社区宣布结果邮件模板

标题：

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

正文：

  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. 投票未通过

若社区投票未通过，则在release分支对代码仓库进行修改，重新打包，发起投票。

在Apache Incubator社区发起投票

1. 更新GPG签名

  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"

提交完svn后，访问 https://downloads.apache.org/incubator/brpc/KEYS，检查内容有没有更新，可能需要等几分钟时间，等内容更新了，再继续下一步。

2. 投票阶段

  1. 发起投票邮件到general@incubator.apache.org。IPMC会进行投票。经过至少72小时并统计到3个+1 IPMC member票后，即可进入下一阶段。
  2. 宣布投票结果，发起投票结果邮件到general@incubator.apache.org。

3. 投票邮件模板

  1. Apache Incubator 社区投票邮件模板

标题：

  1. [VOTE] Release Apache brpc 1.0.0

正文：

  1. Hi Incubator Community,
  3. This is a call for a vote to release Apache brpc version
  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 社区宣布结果邮件模板

标题：

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

正文：

  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

完成发布

1. 将发布包从Apache SVN仓库 dist/dev 移动至 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. Github版本发布

在 GitHub Releases 页面的对应版本上点击，创建新的Release页面 编辑版本号及版本说明，并点击 Publish release

3. 更新下载页面

等待并确认新的发布版本同步至 Apache 镜像后，更新如下页面：https://brpc.apache.org/docs/downloadbrpc/, 更新方式在 https://github.com/apache/brpc-website/ 仓库中，注意中英文都要更新。

GPG签名文件和哈希校验文件的下载链接应该使用这个前缀：https://downloads.apache.org/incubator/brpc/

代码包的下载链接应该使用这个前缀：https://dlcdn.apache.org/incubator/brpc/

4. 发送邮件通知发布完成

发送邮件到dev@brpc.apache.org、general@incubator.apache.org、和announce@apache.org通知完成版本发布。

注意：发邮件账号必须使用个人apache邮箱，且邮件内容必须是纯文本格式（可在gmail选择”纯文本模式”）。announce@apache.org 邮件组需要经过人工审核才能送达，发出邮件后请耐心等待，一般会在一天之内通过。

通知邮件模板如下：

标题：

  1. [ANNOUNCE] Apache brpc 1.0.0 released

正文：
注：Brief notes of this release仅需列出本次发版的主要变更，且无需指出对应贡献人和PR编号，建议参考下之前的Announce邮件。

  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. brpc Resources:
  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!
  35. Best Regards,
  36. Apache brpc community

发布微信公众号公告

参考 https://mp.weixin.qq.com/s/DeFhpAV_AYsn_Xd1ylPTSg.

更新master分支

发版完成后，将release分支合并到master分支.

修改于 2023年2月13日: add the new committer Zhaogeng Li (#133) (ade03ff)