diff --git a/doc/apache/apache-release-procedure-20200306.md b/doc/apache/apache-release-procedure-20200306.md new file mode 100644 index 0000000000000000000000000000000000000000..3f677ff56b8a97f881ae3d1b9bf842754ddb05ab --- /dev/null +++ b/doc/apache/apache-release-procedure-20200306.md @@ -0,0 +1,448 @@ + +# Apache 软件发版流程 + +> author: wongoo@apache.org +> last updated: 2020-03-06 + +Apache开源软件是有社区驱动的，为了提高发布软件质量而指定了软件发布流程，本文主要介绍此流程，以给第一次发布打包的apacher参考。 + +如果你要准备打包一个apache软件了，想必你已经是一个项目的committer了，而且知道社区、PMC这些概念，而你现在还担任本次发布的 release manager 一职。 + +发版流程其实也很简单，无非如下： +1. 整理变更内容，打包并对打包文件签名； +2. 将签名文件上传apache svn仓库； +3. 发邮件请社区PMC大佬投票； +4. 投票通过后发一个投票结果通告邮件； +5. 发版 +6. 发版邮件通告社区新版本发布； + +下面详细整理发版的一些流程步骤，使用 dubbo 的子项目 dubbog-go-hessian2 发版为例！ + + +## 1. 发版准备 + +发版文件需要签名，需要安装pgp工具. + +```bash +$ brew install gpg +$ gpg --version +$ gpg --full-gen-key + (1) RSA and RSA (default) <-- RSA 类型 + What keysize do you want? (2048) 4096 <-- key大小为4096 + 0 = key does not expire <-- 永不过期 + Real name: Liu Yang + Email address: wongoo@apache.org + Comment: CODE SIGNING KEY + + gpg: /Users/gelnyang/.gnupg/trustdb.gpg: trustdb created + gpg: key 7DB68550D366E4C0 marked as ultimately trusted + gpg: revocation certificate stored as '/Users/gelnyang/.gnupg/openpgp-revocs.d/1376A2FF67E4C477573909BD7DB68550D366E4C0.rev' + public and secret key created and signed. + + pub rsa4096 2019-10-17 [SC] + 1376A2FF67E4C477573909BD7DB68550D366E4C0 + uid Liu Yang (CODE SIGNING KEY) <wongoo@apache.org> + sub rsa4096 2019-10-17 [E] + +$ gpg --list-keys + gpg: checking the trustdb + gpg: marginals needed: 3 completes needed: 1 trust model: pgp + gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u + /Users/gelnyang/.gnupg/pubring.kbx + ---------------------------------- + pub rsa4096 2019-10-17 [SC] + 1376A2FF67E4C477573909BD7DB68550D366E4C0 + uid [ultimate] Liu Yang (CODE SIGNING KEY) <wongoo@apache.org> + sub rsa4096 2019-10-17 [E] + + +# 公钥服务器是网络上专门储存用户公钥的服务器 +# 通过key id发送public key到keyserver +$ gpg --keyserver pgpkeys.mit.edu --send-key 1376A2FF67E4C477573909BD7DB68550D366E4C0 + gpg: sending key 7DB68550D366E4C0 to hkp://pgpkeys.mit.edu +# 其中，pgpkeys.mit.edu为随意挑选的keyserver，keyserver列表为：https://sks-keyservers.net/status/，为相互之间是自动同步的，选任意一个都可以。 + +# 如果有多个public key，设置默认key。修改 ~/.gnupg/gpg.conf +$ vi ~/.gnupg/gpg.conf +default-key 7DB68550D366E4C0 + +# 如果有多个public key, 也可以删除无用的key： +### 先删除私钥，再删除公钥 +$ gpg --yes --delete-secret-keys shenglicao2@gmail.com ###老的私钥，指明邮箱即可 +$ gpg --delete-keys 1808C6444C781C0AEA0AAD4C4D6A8007D20DB8A4 + +## 由于公钥服务器没有检查机制，任何人都可以用你的名义上传公钥，所以没有办法保证服务器上的公钥的可靠性。 +## 通常，你可以在网站上公布一个公钥指纹，让其他人核对下载到的公钥是否为真。 +# fingerprint参数生成公钥指纹： +$ gpg --fingerprint wongoo + + pub rsa4096 2019-10-17 [SC] + 1376 A2FF 67E4 C477 5739 09BD 7DB6 8550 D366 E4C0 + uid [ultimate] Liu Yang (CODE SIGNING KEY) <wongoo@apache.org> + sub rsa4096 2019-10-17 [E] + # 将上面的 fingerprint （即 1376 A2FF 67E4 C477 5739 09BD 7DB6 8550 D366 E4C0）粘贴到自己的用户信息中： + # https://id.apache.org OpenPGP Public Key Primary Fingerprint: +``` + +> 详细参考： +> - 发布签名: http://www.apache.org/dev/release-signing.html +> - 发布策略: http://www.apache.org/dev/release-distribution +> - 将密钥上传到公共密钥服务器: https://www.apache.org/dev/openpgp.html#generate-key + +## 2. 打包签名 + +准备打包前（尤其提第一次打包）需要注意以下内容: +- 每个文件的LICENSE头部是否正确, 包括 `*.java`, `*.go`, `*.xml`, `Makefile` 等 +- LICENSE 文件是否存在 +- NOTICE 文件是否存在 +- CHANGE.md 是否存在 （变更内容格式符合规范） + +以上可以参考其他已发布项目的配置。 + + +``` + +# NOTICE: 这里切分支，分支名称不要和版本号（tag用）类似，不然会有冲突 +$ git checkout -b 1.4 + +$ git tag -a v1.4.0-rc1 -m "v1.4.0 release candidate 1" + +$ git push --tags + +# 打包 +$ git archive --format=tar 1.4 --prefix=dubbo-go-hessian2-v1.4.0/ | gzip > dubbo-go-hessian2-v1.4.0-src.tar.gz + +# 签名 +$ gpg -u wongoo@apache.org --armor --output dubbo-go-hessian2-v1.4.0-src.tar.gz.asc --detach-sign dubbo-go-hessian2-v1.4.0-src.tar.gz + +# 验证签名 +$ gpg --verify dubbo-go-hessian2-v1.4.0-src.tar.gz.asc dubbo-go-hessian2-v1.4.0-src.tar.gz + +# hash +$ shasum -a 512 dubbo-go-hessian2-v1.4.0-src.tar.gz > dubbo-go-hessian2-v1.4.0-src.tar.gz.sha512 + +# 验证 hash +$ shasum --check dubbo-go-hessian2-v1.4.0-src.tar.gz.sha512 + +``` + +> 发布版本: http://www.apache.org/dev/release-publishing.html + +## 3. 上传打包文件到svn仓库 + +``` +$ svn checkout https://dist.apache.org/repos/dist/dev/dubbo + +$ cd dubbo + +# 更新 +$ svn update + +# 添加 签名 和 public key 到KEYS文件并提交到SVN仓库 +# 这里是将公钥KEYS放到根目录, 有的项目放到本次打包文件目录 +$ (gpg --list-sigs wongoo && gpg --armor --export wongoo) >> KEYS + +$ mkdir -p dubbo-go-hessian2/v1.4.0-rc1 + +# 拷贝相关文件到新建目录下 + +$ tree dubbo-go-hessian2 +dubbo-go-hessian2 +└── v1.4.0-rc1 + ├── dubbo-go-hessian2-v1.4.0-src.tar.gz + ├── dubbo-go-hessian2-v1.4.0-src.tar.gz.asc + └── dubbo-go-hessian2-v1.4.0-src.tar.gz.sha512 + +$ svn add dubbo-go-hessian2 +$ svn add dubbo-go-hessian2/* +$ svn status +$ svn commit --username wongoo -m "Release dubbo-go-hessian2 v1.4.0-rc1" +``` + +> 详细参考: svn版本管理 https://www.apache.org/dev/version-control.html + + +## 4. 发投票 [VOTE] 邮件 + +发任何邮件都是有一定格式的，你加入社区邮件列表后，就会收到很多这样的邮件，多看看就知道了，具体邮件范本参考文章后面的邮件范本。 + +发完【VOTE】邮件，私下沟通群里面请大佬PMC投票。 +PMC投票会对你上传打包文件进行相关检查, +详细可以了解孵化中的项目发布完整的检查项参考： https://cwiki.apache.org/confluence/display/INCUBATOR2/IncubatorReleaseChecklist + +收到3个binding邮件且超过72小时后，就可以发 投票结果 [RESULT] [VOTE] 邮件了。 + +> 原则上只有PMC的投票才算binding邮件, 当然也可以由社区决定。 + +这一步骤最常见有以下问题： +- 文件签名有问题 +- 引用项目LICENSE问题 +- 单元测试不通过 + +> 另外需要注意: 一个apache项目可能包含很多子项目，项目的PMC可能只对主项目比较了解， 他们并不清楚如何将子项目跑起来，也不知道如何跑单元测试，最好在邮件中附带一个如何进行单元测试的连接。例如 PMC 最了解 java，但子项目是golang，python，js等，你需要告诉他们如何测试你的项目。 + +可以参考投票规则: https://www.apache.org/foundation/voting.html + +## 5. 发布版本 + +当正式发布投票成功后，先发[Result]邮件，然后就准备 release package。 +将之前在dev下发布的对应rc文件夹下的源码包、签名文件和hash文件拷贝到另一个目录 v1.4.0， +注意文件名字中不要rcxx (可以rename，但不要重新计算签名，hash可以重新计算，结果不会变)。 + +将release包移动到正式版目录。如果你的软件是需要客户从apache下载的，则这一步是必须的。如果不是，比如golang引用github打包地址的则可以忽略。 +``` +svn up +cd dubbo-go-hessian2 +svn move v1.4.0-rc1 v1.4.0 +svn status +svn commit --username wongoo -m "Release dubbo-go-hessian2 v1.4.0" +``` + +移到发版目录后，还需要进行相应的正式版本发布， 这里将具体发布方式整理到单独的章节 `7. 不同语言版本发布`，因为发布流程马上就要结束了 ^v^ + + +## 6. 新版本通告 ANNOUNCE 邮件 + +恭喜你你已经到发版最后一步了，邮件格式参考以下邮件范本！ + + +## 7. 不同语言版本发布 + +### 7.1 golang + +在 github 基于投票分支发布了 release 版本。 + +### 7.2 java + +java项目发版需发布到java maven仓库。 + +TODO + +### 7.3 js + +js项目发版需发布到npm仓库。 + +TODO + +### 7.4 python + +TODO + +## 8. 邮件范本 + +### 8.1. 提出发版投票 + +- TO: dev@dubbo.apache.org +- Title: [VOTE] Release Apache dubbo-go-hessian2 v1.4.0 RC1 + +``` +Hello Dubbo/Dubbogo Community, + + This is a call for vote to release Apache dubbo-go-hessian2 version v1.4.0 RC1. + + The release candidates: https://dist.apache.org/repos/dist/dev/dubbo/dubbo-go-hessian2/v1.4.0-rc1/ + Git tag for the release: https://github.com/apache/dubbo-go-hessian2/tree/1.4 + Hash for the release tag: 4c31e88c35afe84c0321d9f12f036e6d3c8962d0 + Release Notes: https://github.com/apache/dubbo-go-hessian2/blob/1.4/CHANGE.md + The artifacts have been signed with Key :7DB68550D366E4C0, which can be found in the keys file: + https://dist.apache.org/repos/dist/dev/dubbo/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 Dubbo-go Team + ``` + + +### 8.2. PMC 投票邮件回复 + + +范例1： +``` ++1 approve <-- 首先表明同不同意 + +I have checked: <-- 其次要说明自己检查了哪些项 + +1.source code can build <-- 能否构建 +2.tests can pass in my local <-- 单元测试能否通过 +3. NOTICE LICENSE file exist <-- 协议文件是否存在 +4.git tag is correct <-- git tag 是否正确 + +there is one minor thing that in change logs file, there is no space +between text And link. I suggest add one to make it looks better. <--- 一些其他改进建议 +``` + +范例2： +``` ++1 + +I checked the following items: + +[v] Are release files in correct location? <-- 发布文件目录是否正确 +[v] Do release files have the word incubating in their name? +[v] Are the digital signature and hashes correct? <-- 签名、hash是否正确 +[v] Do LICENSE and NOTICE files exists? +[v] Is the LICENSE and NOTICE text correct? <-- 协议文本是否正确 +[v] Is the NOTICE year correct? <-- 注意年份是否正确 +[v] Un-included software dependencies are not mentioned in LICENSE or NOTICE? <-- 没有包含协议或注意没有提到的软件依赖 +[v] License information is not mentioned in NOTICE? <-- 协议信息没有在注意中提及 +[x] Is there any 3rd party code contained inside the release? If so: <-- 是否包含第三方代码 + [ ] Does the software have a compatible license? + [ ] Are all software licenses mentioned in LICENSE? + [ ] Is the full text of the licenses (or pointers to it) in LICENSE? + Is any of this code Apache licensed? Do they have NOTICE files? If so: + [ ] Have relevant parts of those NOTICE files been added to this NOTICE file? +[v] Do all source files have ASF headers? <-- 是否所有源码都有ASF头部 +[v] Do the contents of the release match with what's tagged in version control? <-- 发布的文件是否和github中tag标记的版本一致 +[x] Are there any unexpected binary files in the release? <-- 是否包含不应该存在的二进制文件 +[v] Can you compile from source? Are the instruction clear? <-- 能否编译？指令是否明确？ + +On my mac laptop, I could compile successfully but there's one failed unit +test against net.go. I believe this issue [1] can be fixed with [2] in the +next release. <-- 编译问题及建议 + +Is the issue minor? <-- 编译存在的问题是否都是较小的？ +[v] Yes [ ] No [ ] Unsure + +Could it possibly be fixed in the next release? <-- 能否在下一版本修复？ +[v] Yes [ ] No [ ] Unsure + +I vote with: <-- 我的投票 +[v] +1 release the software +[ ] +0 not sure if it should be released +[ ] -1 don’t release the software because... + +Regards, +-Ian. + +1. https://github.com/apache/dubbo-go/issues/207 +2. https://github.com/apache/dubbo-go/pull/209 +``` + +范例3： +``` ++1 + +I checked the following items: + +[√] Do LICENSE and NOTICE files exists? +[√] Is the LICENSE and NOTICE text correct? +[√] Is the NOTICE year correct? +[√] Do all source files have ASF headers? +[√] Do the contents of the release match with what's tagged in version control? +[√] Can you compile from source? +I could compile successfully but there's failed units test. I run the unit +test refer to :https://github.com/apache/dubbo-go#running-unit-tests . +But I think it is not matter, the test can be fixed in next release. + + +I vote with: +[√] +1 release the software +``` + +范例4: +``` +Great improvement over the previous release but there are still issues from the last vote that have not been resolved. e.g. [6][7][8] + +Can someone tell me if these files [1][2][3][4][5] are just missing ASF headers or have a different license? + +If they are just missing headers and [6][7][8] explained then it +1 form me, otherwise it’s probably a -1. + +Can people please carefully check the contents, and write down what you checked, rather than just saying +1. + +I checked: +- signatures and hashes good +- LICENSE is missing the appendix (not a major issue) +- LICENSE may be is missing some information[1][2][3][4][5] +- NOTICE is fine +- No binaries in source release +- Some files are missing ASF headers or other license headers [1][2][3][4][5] - please fix + +Thanks, +Justin + +1. dubbo-go-1.1.0/cluster/loadbalance/round_robin_test.go +2. dubbo-go-1.1.0/common/extension/router_factory.go +3. dubbo-go-1.1.0/config_center/configuration_parser.go +4. dubbo-go-1.1.0/config_center/configuration_parser_test.go +5. dubbo-go-1.1.0/registry/zookeeper/listener_test.go +6. dubbo-go-1.1.0/cluster/loadbalance/least_active.go +7. dubbo-go-1.1.0/protocol/RpcStatus.go +8. dubbo-go-1.1.0/filter/impl/active_filter.go +``` + + +### 8.3. 发 [RESULT] [VOTE] 投票结果通知邮件 + +- TO: dev@dubbo.apache.org +- Title: [RESULT] [VOTE]: Release Apache dubbo-go-hessian2 v1.4.0 RC1 + + +``` +Hello Dubbo/Dubbogo Community, + +The release dubbo-go-hessian2 v1.4.0 RC1 vote finished, We’ve received 3 +1 (binding) votes. + ++1 binding, Stocks Alex ++1 binding, Ian Luo ++1 binding, Jun Liu + +The vote and result thread: +https://lists.apache.org/thread.html/r8070f3b00984888069dd4ddad1bbc424cde51ea68b6ff0520e609e18%40%3Cdev.dubbo.apache.org%3E + + +The vote passed. Thanks all. +I will proceed with the formal release later. + + +Best regards, + +The Apache Dubbogo Team +``` + + +### 8.4. 发 Announce 发版邮件 + +- TO: dev@dubbo.apache.org +- [ANNOUNCE] Apache Dubbo version 2.7.4 Released + +``` +Hello Community, + +The Apache Dubbo team is pleased to announce that the 2.7.4 has been +released. + +Apache Dubbo™ is a high-performance, java based, open source +RPC framework. Dubbo offers three key functionalities, which include +interface based remote call, fault tolerance & load balancing, and +automatic service registration & discovery. + +Both the source release[1] and the maven binary release[2] are available +now, you can also find the detailed release notes in here[3]. + + +If you have any usage questions, or have problems when upgrading or find +any problems about enhancements included in this release, please don’t +hesitate to let us know by sending feedback to this mailing list or filing +an issue on GitHub[4]. + + + +[1] http://dubbo.apache.org/en-us/blog/download.html +[2] http://central.maven.org/maven2/org/apache/dubbo +[3] https://github.com/apache/dubbo/releases +[4] https://github.com/apache/dubbo/issues +``` + +## 9. 参考 + +- dubbo发布流程: http://dubbo.apache.org/zh-cn/docs/developers/committer-guide/release-guide_dev.html +- doris发布流程: https://github.com/apache/incubator-doris/blob/master/docs/documentation/cn/community/release-process.md +- spark发布流程: http://spark0apache0org.icopy.site/release-process.html + + diff --git a/doc/apache/release_note.md b/doc/apache/release_note.md new file mode 100644 index 0000000000000000000000000000000000000000..747a3348a1324cc059906fae16cb432b3bc6188d --- /dev/null +++ b/doc/apache/release_note.md @@ -0,0 +1,11 @@ +### How to release a new version? +--- + +* 1 Check the time range of NOTICE; +* 2 Add the features to the feature list of README.md/README_CN.md/CHANGE.md; +* 3 Check whether every code file has the Apache License 2.0 or not; +* 4 There should not be author info(name & email etc) exist in code file; +* 5 Run all unit tests; +* 6 Run all samples in apache/dubbo-samples/golang; +* 7 Write "What's New" by releaser who should be an apache/dubbo-go committer; +* 8 And then, u can release a new version refer to [Apache 软件发版流程](./apache-release-procedure-20200306.md); \ No newline at end of file diff --git a/go.mod b/go.mod index 8d6647e105753f8adb98b46552ac6526988cc9d0..f986ba6adb725efcf8d4ee024adc6609275f5f52 100644 --- a/go.mod +++ b/go.mod @@ -4,7 +4,7 @@ require ( github.com/Workiva/go-datastructures v1.0.50 github.com/afex/hystrix-go v0.0.0-20180502004556-fa1af6a1f4f5 github.com/aliyun/alibaba-cloud-sdk-go v0.0.0-20190802083043-4cd0c391755e // indirect - github.com/apache/dubbo-go-hessian2 v1.3.1-0.20200302092433-6ae5479d93a3 + github.com/apache/dubbo-go-hessian2 v1.4.0 github.com/buger/jsonparser v0.0.0-20181115193947-bf1c66bbce23 // indirect github.com/coreos/bbolt v1.3.3 // indirect github.com/coreos/etcd v3.3.13+incompatible diff --git a/go.sum b/go.sum index ef5649e8c398f01adf18c3eb162bd6f3f9c78bdc..3bbae5009bd0e6e70cc6c8de25ced97e0e40748e 100644 --- a/go.sum +++ b/go.sum @@ -35,8 +35,8 @@ github.com/alecthomas/units v0.0.0-20151022065526-2efee857e7cf/go.mod h1:ybxpYRF github.com/aliyun/alibaba-cloud-sdk-go v0.0.0-20190802083043-4cd0c391755e h1:MSuLXx/mveDbpDNhVrcWTMeV4lbYWKcyO4rH+jAxmX0= github.com/aliyun/alibaba-cloud-sdk-go v0.0.0-20190802083043-4cd0c391755e/go.mod h1:myCDvQSzCW+wB1WAlocEru4wMGJxy+vlxHdhegi1CDQ= github.com/aliyun/aliyun-oss-go-sdk v0.0.0-20190307165228-86c17b95fcd5/go.mod h1:T/Aws4fEfogEE9v+HPhhw+CntffsBHJ8nXQCwKr0/g8= -github.com/apache/dubbo-go-hessian2 v1.3.1-0.20200302092433-6ae5479d93a3 h1:1HM47ILUkLaMxLKUub+WHPncqrJGEQ0KRJzSJueMDpY= -github.com/apache/dubbo-go-hessian2 v1.3.1-0.20200302092433-6ae5479d93a3/go.mod h1:VwEnsOMidkM1usya2uPfGpSLO9XUF//WQcWn3y+jFz8= +github.com/apache/dubbo-go-hessian2 v1.4.0 h1:Cb9FQVTy3G93dnDr7P93U8DeKFYpDTJjQp44JG5TafA= +github.com/apache/dubbo-go-hessian2 v1.4.0/go.mod h1:VwEnsOMidkM1usya2uPfGpSLO9XUF//WQcWn3y+jFz8= github.com/armon/circbuf v0.0.0-20150827004946-bbbad097214e h1:QEF07wC0T1rKkctt1RINW/+RMTVmiwxETico2l3gxJA= github.com/armon/circbuf v0.0.0-20150827004946-bbbad097214e/go.mod h1:3U/XgcO3hCbHZ8TKRvWD2dDTCfh9M9ya+I9JpbB7O8o= github.com/armon/go-metrics v0.0.0-20180917152333-f0300d1749da/go.mod h1:Q73ZrmVTwzkszR9V5SSuryQ31EELlFMUz1kKyl939pY=