apache · liyijuan · Jun 28, 2022 · Jun 28, 2022 · Jun 28, 2022 · Jun 30, 2022
diff --git a/docs/29how-to-contribute.md b/docs/29how-to-contribute.md
@@ -1 +1,118 @@
 # how-to-contribute
+
+Apache RocketMQ —— 开放共享的开源社区，诚挚邀请您的加入
+
+社区交流和贡献方式：
+
+- 提出问题
+- 提交错误报告
+- 提出新特性
+- 参与邮件列表上的讨论
+- 贡献代码或文档
+- 优化网站
+- 测试预发布版本
+
+
+## 提出问题！
+
+Apache RocketMQ 社区提供完备的处理流程帮您解答问题。 您可以通过 [user mailing list](https://rocketmq.apache.org/about/contact/) 和 [apache-rocketmq](https://stackoverflow.com/questions/tagged/rocketmq) 进行提问。
+
+## 提交错误报告
+
+如您在使用 RocketMQ 过程中出现问题，可以在 [Github Issue](https://github.com/apache/rocketmq/issues) 上提交错误报告。
+
+## 提出改进或新功能
+
+社区在持续寻找反馈意见以改善 Apache RocketMQ ，您的改进方案或新特性的需求将惠及所有 RocketMQ 用户, 请在 github 上创建 [Github Issue](https://github.com/apache/rocketmq/issues)。
+
+提案需要包含适当的细节描述和影响范围，如果可能的话详述其需求。我们希望得到尽可能完备的信息，原因如下：
+
+* 实现的改进和新特性最终符合您的需求
+* 根据您的需求评估投入成本和设计解决方案
+* 便于社区围绕该提案展开建设性的讨论
+
+若您计划实现自己的提案以贡献社区，同样需要提供详细描述信息，并遵循 [code-guidelines](/docs/30code-guidelines) 中的编码规范
+
+我们推荐先在社区达成共识再着手实现功能。通过讨论新特性的必要性及实现方案等问题，可以早发现超出项目范围的提案。
+
+## 参与讨论并帮助他人
+
+Apache RocketMQ 社区成员主要通过以下两种邮件沟通和交流：
+
+*  [user mailing lists](mailto:[email protected]) ：Apache RocketMQ 用户 通过该邮件列表提问以寻求帮助或建议。您可以通过订阅该邮件系统以帮助他人解决问题来贡献社区。此外, 您还可以在 Stack Overflow 上检索 [rocketmq](https://stackoverflow.com/questions/tagged/rocketmq) 标签 回答用户的问题并获取更多见解。
+*  [development mailing list](mailto:[email protected]) : Apache RocketMQ 开发者 通过该邮件列表交流新特性，预发布版本，一般的开发流程等。若您热衷于为 RocketMQ 社区贡献代码，可以加入该邮件列表。
+
+
+您也可以通过订阅 [mailing lists](/about/contact)，获取更多的社区信息。
+
+
+## 测试预发布版本
+
+Apache RocketMQ 在其活跃社区的推动下持续发展着。每隔几周我们会发布 RocketMQ 的新版本，以修复漏洞，提升性能，新增特性等。发布新版本的流程如下：
+
+1. 推出新的预发布版本并启动投票流程（时效 72 小时）
+2. 测试预发布版本并评分 (+1 未发现问题, -1 测试出问题)
+3. 若预发布版本未测试出问题则发布，否则回到步骤 1
+
+我们在网站上整理了 [release-manual](/docs/32release-manual) 版本发布指南。测试预发行版是项大工程，我们需要吸纳更多人的参与。 RocketMQ 社区鼓励每个人都参与新版本的测试。通过测试预发布版本, 您将确信新的 RocketMQ 版本仍将为您的程序提供正常服务，并确实在支持版本升级。
+
+## 贡献代码
+
+Apache RocketMQ 已然并将持续进行维护，优化，和扩展。因此 Apache RocketMQ 鼓励所有人贡献源代码。为给予代码贡献者和审查者极佳的代码贡献体验，并提供高质量的代码仓库，社区遵循 [code-guidelines](/docs/30code-guidelines) 中的贡献流程。编码手册包含构建开发环境指南，社区编码指南和编码风格，并介绍了如何提交贡献的代码。
+
+
+**请务必在编码之前仔细阅读 [code-guidelines](/docs/30code-guidelines) **
+
+并请阅读 [AFS Apache 软件基金会 贡献者协议](https://www.apache.org/licenses/contributor-agreements.html) 提交电子签名
+
+万事俱备，只差 issue ？
+
+[Github issue](https://github.com/apache/rocketmq/issues) 列出了目前已提出的改进和推荐特性。
+
+## 贡献文档
+
+优秀的说明文档对任何一种软件都是至关重要的。 Apache RocketMQ 社区致力于提供简明，精准，完备的技术文档。社区诚挚邀请所有贡献参与完善和改进 RocketMQ 文档。
+
+* 请在 [Github issue](https://github.com/apache/rocketmq/issues)上报告文档缺失，错误，过期等相关情况
+* RocketMQ 技术文档以 Markdown 形式书写，并存放在 RocketMQ [site source code repository](https://github.com/apache/rocketmq-site/tree/new-official-website/)官网仓库 ```/docs``` 目录下。
+
+阅读 [Q&A](https://github.com/apache/rocketmq-site/tree/new-official-website)了解如何通过更新和完善等方式贡献文档。
+
+## 优化官网
+
+Apache RocketMQ 官网代表着 Apache RocketMQ 和 Apache RocketMQ 社区。其主要功能如下：
+
+* 通晓访问者 Apache RocketMQ 和 Apache RocketMQ 的功能特性
+* 支持访问者 下载并使用 RocketMQ
+* 引导访问者 参与并贡献 RocketMQ 社区
+
+社区接纳任何有助于优化网站的贡献。
+
+请通过创建 [Github issue](https://github.com/apache/rocketmq-site/issues) 提供您关于网站的建议和创意
+
+如您想要更新或优化网站，请阅读[apache/rocketmq-site: Mirror of RocketMQ site](https://github.com/apache/rocketmq-site) 
+
+## 更多贡献途径...
+
+条条大路通罗马，还有更多贡献 RocketMQ 社区的方式等您选择！ 例如您可以：
+
+* 介绍 RocketMQ 给尽可能多的伙伴使用
+* 组织线下交流会或组建线上用户群
+* 化身 RocketMQ 的布道师
+* ...
+
+## 如何成为 committer
+
+Committers 是社区中修改项目仓库的成员，可修改代码，文档和网站或接纳其他成员的贡献。
+
+成为 commiter 并没有严格的协议，候选人通常是社区中活跃的贡献者
+
+活跃的贡献者意味着：参加邮箱列表中的讨论，帮助他人解决问题，验证预发布版本，礼贤下士并持续优化社区管理，这部分关乎社区在 Apache 中的发展。
+
+无疑，为项目贡献代码和文档同样至关重要。好的开端可以是优化性能，开发新特性，修复漏洞。无论哪种方式，您需要为所贡献的代码负责，提供测试用例和说明文档并持续维护。
+
+候选人可以被社区内的 committer 或 PMC 成员举荐，并最终由 PMC 投票表决。
+
+如您有意成为 RocketMQ 社区的 committer ，请积极融入社区并以上述任意方式贡献 Apache RocketMQ  
+
+社区内 committer 成员会非常热衷与您分享交流，并给予您适时的建议和指导。
diff --git a/docs/30code-guidelines.md b/docs/30code-guidelines.md
@@ -1 +1,38 @@
 # code-guidelines
+
+# 前言
+
+本文向您介绍编写软件源码的规范和指南。
+
+研究表明研发代码的 80% 时间用于软件维护，包括软件源码解读，源码重构，源码维护
+
+制定并强制推行编码规则和编码指南，有助于提高代码的可读性，强化团队代码的所有权，
+
+帮助工程师快速且深入理解新增代码，简化维护的
+
+# IDEA 编码模板
+
+这个标题可能需要修改一下，结合后面内容的理解
+
+## 导入 code style
+
+
+
+## 导入版权
+
+
+
+## 选择 Apache 版权
+
+
+
+## 移除作者 javadoc 标签
+
+
+
+内容最好有点说明，至少简要说明为什么要这么做，还有就是 标题，简洁优雅还有切合主流说法
+
+
+
+
+
diff --git a/docs/31pull-request.md b/docs/31pull-request.md
@@ -1 +1,216 @@
 # pull-request
+
+本文将引导您通过 Git 贡献 RocketMQ
+
+# Github 远程仓库
+
+本小节作为前置知识，简要说明使用 Git 贡献 RocketMQ 原因，有相关基础的同学可以自行跳过
+
+首先您需要自行了解 Git 和 Github 相关概念
+
+思考：从开发者角度，如何与他人协作完成项目？
+
+如果您想到通过打包压缩然后复制粘贴的方式，那么请再试想一下扩大参与者的范围至 10k+ 级别
+
+这就是远程仓库的意义：开发者可以很方便地从 Github 上获取仓库代码，并提交开发分支到远程仓库与他人交流和共享
+
+![1656601484232](picture/31pull-request/1_Github.png)
+
+那么，有了这个公共仓库，然后呢？
+
+如何下载远程仓库的代码？
+
+如何提交开发分支到远程仓库？
+
+如何使开发分支相互可见？
+
+薅头发的请先住手，Linus 大神已经提供了解决方案 Git
+
+# Git 贡献指南
+
+① 复刻 [apache/rocketmq](https://github.com/apache/rocketmq) 仓库至个人 Github 远程仓库
+
+```shell
+https://github.com/cuser/rocketmq.git # cuser's rocketmq repo[repository] url
+```
+
+说明：```cuser``` GitHub用户名，```Fork``` 后可通过个人主页 Repositories ，找到复刻仓库并查看地址
+
+② 自行安装 Git 并克隆到本地仓库
+
+```shell
+git clone https://github.com/cuser/rocketmq.git # git clone [repo url]
+```
+
+说明：克隆到的本地仓库会以 GitHub 仓库作为远程仓库，并以```origin```命名远程仓库
+
+③ 添加并命名远程仓库
+
+```shell
+git remote add apache https://github.com/cuser/rocketmq.git	# git remote add [repo name] [repo url]
+```
+
+说明：可以使用 git remote add 指定远程仓库并命名，若跳过该步，后续流程请使用```origin```作为仓库名
+
+④ 拉取远程仓库开发分支
+
+```shell
+git fetch apache develop # git fetch [repo name] [repo branch]
+```
+
+说明：develop 为默认开发分支，可在 GitHub 仓库主页 ```branches``` 标签处了解详情
+
+⑤ 获取开发分支最新代码
+
+```shell
+git rebase apache/develop # git rebase [branch]
+```
+
+说明： [rebase <branch>](https://git-scm.com/docs/git-rebase) 基本说法是换基，可通过链接示例了解该步的必要性
+
+⑥ 在本地仓库执行更改
+
+```shell
+git checkout -b RocketMQ-Vxx.0 # git checkout [-b] [new-branch]
+git add /rocketmq/pom.xml # git add [dir/file]
+git commit -a -m "pom"	# git commit [-all] [-msg] [message]
+```
+
+说明： 参考[Git](https://git-scm.com/docs/git-add)了解详情，使用相对路径请切换至 ```.git``` 同级目录
+
+⑦ 推送更改到远程仓库
+
+```shell
+git push --set-upstream apache RocketMQ-Vxx.0	# push branch to https://github.com/cuser/rocketmq-site.git
+```
+
+说明：若未创建远程仓库，替换 ```apache``` 为 ``` origin```
+
+# Github 提交 PR
+
+如下：以提交 PR 至 ```new-official-website``` 分支为例说明 PR 流程
+
+参照```Git 贡献指南```在本地仓库修改完毕，并将该分支推送到 Github 远程仓库
+
+```shell
+git checkout new-official-website	# git checkout -b new-official-website
+git push origin new-official-website	# push to https://github.com/cuser/rocketmq-site.git
+```
+
+① Github 远程仓库切换至开发分支 new-official-website
+
+![1656576449012](picture/31pull-request/2_switch branch.png)
+
+② 创建合并请求，点击 Contribute 下的 Open pull request
+
+![1656576385381](picture/31pull-request/3_OpenPR.png)
+
+③ compare across forks 选择请求分支和开发分支
+
+![1656580236831](picture/31pull-request/4_compare.png)
+
+base repository / base : 请求仓库及请求分支
+
+head repository / compare : 开发仓库及开发分支
+
+注意请务必正确选择请求分支与开发分支，并请在得到分支所有者许可后再请求合入
+
+④ 填写首字母大写的 PR 摘要，并在 Write 标签下简要描述 PR 内容
+
+![1656589498318](picture/31pull-request/5_Write.png)
+
+	提交 PR 前，请先做如下确认：
+
+1. 已创建与 PR 对应的 [Github issue]( [apache/rocketmq: Mirror of Apache RocketMQ (github.com)](https://github.com/apache/rocketmq/issues) )
+2. 修改内容符合 [Coding Guidelines](/docs/30code-guidelines) 编程规范
+3. pull request 摘要以 [ISSUE #XXX] 开始并简要描述变更需求
+4. 概述 PR 变更需求，变更日志，验证信息，可参考 [demo pull request](https://github.com/apache/rocketmq/pull/152) 
+5. 提交内容具备完整的测试用例，并确保基本检查，单元测试，集成测试通过
+6. 若贡献值较高，请提交 [Apache个人贡献者许可协议](http://www.apache.org/licenses/#clas) 
+
+⑤ 点击 "Create pull request" ，请求合并该分支
+
+![1656589565022](picture/31pull-request/6_CreatePR.png)
+
+⑥ 至此，PR 已经在 apache/rocketmq-site 远程仓库上可见，所有协作者都可以 Review 该PR 并提供建议
+
+![1656601854040](picture/31pull-request/7_mailList.png)
+
+您可以根据评论在本地完成修改并进行多次提交。请求合并和提交修改的相关信息会同步展示在 PR 页面、	    
+
+issue 列表、RocketMQ 的邮件列表中，以便提醒 committer 及时审核 PR
+
+# 合并 PR
+
+开源项目开发分支合并由 committer 完成，所以，向上吧，少年！
+
+① 合并 contributor PR
+
+```shell
+git checkout develop	# switch to local develop branch
+git pull apache develop	# fast-forward to current remote HEAD
+git pull --squash https://github.com/cuser/rocketmq.git RocketMQ-Vxx.0  # merge to branch
+```
+
+拉取的请求合并分支可能包含多次提交，建议使用 ```--squash``` 指令压缩为一次 commit
+
+合并前务必要解决合并冲突，并确保当前分支同步于远程分支
+
+请阅读 [Git pull]( [Git - git-pull Documentation (git-scm.com)](https://git-scm.com/docs/git-pull) ) 了解 fast-forward 等相关详情
+
+② 合并 committer PR
+
+若 committer 合并自己的 PR , 使用 [Git merge]( [Git - git-merge Documentation (git-scm.com)](https://git-scm.com/docs/git-merge) ) 即可
+
+```shell
+git checkout develop      # switch to local develop branch
+git pull apache develop   # fast-forward to current remote HEAD
+git merge --squash RocketMQ-Vxx.0	# merge to branch
+```
+
+③ 进行常规的补丁检查，使用内置的测试用例构建项目，并请务必修改 changelog 
+
+④ 若上述工作均已完成，可以执行下面的指令提交合并，回馈开发者分支状态，并关闭 PR
+
+```shell
+git commit --author="contributor_name <contributor_email>" -a -m "RocketMQ-Vxx.0 description closes apache/rocketmq#ZZ"
+```
+
+关闭 PR 的详情，请参考 [Close PR](https://docs.github.com/cn/issues/tracking-your-work-with-issues/closing-an-issue) 
+
+⑤ 将合并后的分支推送到 apache/rocketmq 远程仓库
+
+```shell
+git push apache develop
+```
+
+⑥ PR 被提交后，会保留到 GitHub 远程仓库，也可以同步更新个人 GitHub 仓库
+
+```shell
+git push origin develop
+```
+
+关于合并修改的建议：squash 会丢弃开发分支的 commit 信息
+
+# 拒绝 PR
+
+拒绝 PR ：意味着并不执行 pull 或 merge，而仅仅提交拒绝 PR 信息
+
+```SHELL
+git commit --allow-empty -m "RocketMQ-Vxx.0 closes apache/rocketmq#ZZ *Won't fix*"
+git push apache develop
+```
+
+关闭 Github 上编号 #ZZ 的 PR
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/picture/31pull-request/1_Github.png b/docs/picture/31pull-request/1_Github.png
diff --git a/docs/picture/31pull-request/2_switch branch.png b/docs/picture/31pull-request/2_switch branch.png
diff --git a/docs/picture/31pull-request/3_OpenPR.png b/docs/picture/31pull-request/3_OpenPR.png
diff --git a/docs/picture/31pull-request/4_compare.png b/docs/picture/31pull-request/4_compare.png
diff --git a/docs/picture/31pull-request/5_Write.png b/docs/picture/31pull-request/5_Write.png
diff --git a/docs/picture/31pull-request/6_CreatePR.png b/docs/picture/31pull-request/6_CreatePR.png
diff --git a/docs/picture/31pull-request/7_mailList.png b/docs/picture/31pull-request/7_mailList.png