Skip to content

Commit 294c267

Browse files
slievrlyslievrly
authoredNov 7, 2022
optimize: add contributing docs (alibaba#35)
1 parent 98555bf commit 294c267

File tree

4 files changed

+451
-2
lines changed

4 files changed

+451
-2
lines changed
 

‎.licenserc.yaml

+1-2
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@ header:
55

66
paths-ignore:
77
- '.gitignore'
8-
- 'README.md'
9-
- 'README_EN.md'
8+
- '*.md'
109
- 'LICENSE'
1110
- '.github/**'
1211
- '.licenserc.yaml'

‎CODE_OF_CONDUCT.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, sex characteristics, gender identity and expression,
9+
level of experience, education, socio-economic status, nationality, personal
10+
appearance, race, religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at higress@googlegroups.com. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72+
73+
[homepage]: https://www.contributor-covenant.org
74+
75+
For answers to common questions about this code of conduct, see
76+
https://www.contributor-covenant.org/faq

‎CONTRIBUTING_CN.md

+187
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# 为 Higress 做贡献
2+
3+
如果你有兴趣寻找关于Higress的漏洞，我们会热烈欢迎。首先，我们非常鼓励这种意愿。这是为您提供的贡献指南列表。
4+
5+
[[English Contributing Document](./CONTRIBUTING_EN.md)]
6+
7+
## 话题
8+
9+
* [报告安全问题](#报告安全问题)
10+
* [报告一般问题](#报告一般问题)
11+
* [代码和文档贡献](#代码和文档贡献)
12+
* [测试用例贡献](#测试用例贡献)
13+
* [参与帮助任何事情](#参与帮助任何事情)
14+
* [代码风格](#代码风格)
15+
16+
## 报告安全问题
17+
18+
安全问题总是得到认真对待。作为我们通常的原则，我们不鼓励任何人传播安全问题。如果您发现Higress的安全问题，请不要公开讨论，甚至不要公开问题。相反，我们鼓励您向 [higress@googlegroups.com](mailto:higress@googlegroups.com) 发送私人电子邮件 以报告此情况。
19+
20+
## 报告一般问题
21+
22+
老实说，我们把每一个 Higress 用户都视为非常善良的贡献者。在体验了 Higress 之后，您可能会对项目有一些反馈。然后随时通过 [NEW ISSUE](https://github. com/alibaba/higress/issues/new/choose)打开一个问题。
23+
24+
因为我们在一个分布式的方式合作项目Higress，我们欣赏写得很好的，详细的，准确的问题报告。为了让沟通更高效，我们希望每个人都可以搜索您的问题是否在搜索列表中。如果您发现它存在，请在现有问题下的评论中添加您的详细信息，而不是打开一个全新的问题。
25+
26+
为了使问题细节尽可能标准，我们为问题报告者设置了一个[问题模板](./.github/ISSUE_TEMPLATE) 请务必按照说明填写模板中的字段。
27+
28+
有很多情况你可以打开一个问题：
29+
30+
* 错误报告
31+
* 功能要求
32+
* 性能问题
33+
* 功能提案
34+
* 功能设计
35+
* 需要帮助
36+
* 文档不完整
37+
* 测试改进
38+
* 关于项目的任何问题
39+
* 等等
40+
41+
另外我们必须提醒的是，在填写新问题时，请记住从您的帖子中删除敏感数据。敏感数据可能是密码、密钥、网络位置、私人业务数据等。
42+
43+
## 代码和文档贡献
44+
45+
鼓励采取一切措施使 Higress 项目变得更好。在 GitHub 上，Higress 的每项改进都可以通过 PR（Pull Request的缩写）实现。
46+
47+
* 如果您发现错别字，请尝试修复它！
48+
* 如果您发现错误，请尝试修复它！
49+
* 如果您发现一些多余的代码，请尝试删除它们！
50+
* 如果您发现缺少一些测试用例，请尝试添加它们！
51+
* 如果您可以增强功能，请**不要**犹豫！
52+
* 如果您发现代码晦涩难懂，请尝试添加注释以使其更加易读！
53+
* 如果您发现代码丑陋，请尝试重构它！
54+
* 如果您能帮助改进文档，那就再好不过了！
55+
* 如果您发现文档不正确，只需执行并修复它！
56+
* ...
57+
58+
实际上不可能完整地列出它们。记住一个原则：
59+
60+
> 我们期待您的任何PR。
61+
62+
由于您已准备好通过 PR 改进 Higress，我们建议您可以在此处查看 PR 规则。
63+
64+
* [工作区准备](#工作区准备)
65+
* [分支定义](#分支定义)
66+
* [提交规则](#提交规则)
67+
* [PR说明](#PR说明)
68+
69+
### 工作区准备
70+
71+
为了提出 PR，我们假设你已经注册了一个 GitHub ID。然后您可以通过以下步骤完成准备工作：
72+
73+
1. **FORK** Higress 到您的存储库。要完成这项工作，您只需单击 [alibaba/higress](https://github.com/alibaba/higress) 主页右侧的 Fork 按钮。然后你将在
74+
中得到你的存储库`https://github.com/<your-username>/higress`，其中your-username是你的 GitHub 用户名。
75+
76+
2. **克隆** 您自己的存储库以在本地开发. 用于 `git clone git@github.com:<your-username>/higress.git` 将存储库克隆到本地计算机。 然后您可以创建新分支来完成您希望进行的更改。
77+
78+
3. **设置远程** 将上游设置为 `git@github.com:alibaba/higress.git` 使用以下两个命令：
79+
80+
```bash
81+
git remote add upstream git@github.com:alibaba/higress.git
82+
git remote set-url --push upstream no-pushing
83+
```
84+
85+
使用此远程设置，您可以像这样检查您的 git 远程配置：
86+
87+
```shell
88+
$ git remote -v
89+
origin git@github.com:<your-username>/higress.git (fetch)
90+
origin git@github.com:<your-username>/higress.git (push)
91+
upstream git@github.com:alibaba/higress.git (fetch)
92+
upstream no-pushing (push)
93+
```
94+
95+
添加这个，我们可以轻松地将本地分支与上游分支同步。
96+
97+
### 分支定义
98+
99+
现在我们假设通过拉取请求的每个贡献都是针对Higress 中的 [开发分支](https://github.com/alibaba/higress/tree/develop) 。在贡献之前，请注意分支定义会很有帮助。
100+
101+
作为贡献者，请再次记住，通过拉取请求的每个贡献都是针对分支开发的。而在Higress项目中，还有其他几个分支，我们一般称它们为release分支（如0.6.0、0.6.1）、feature分支、hotfix分支和master分支。
102+
103+
当正式发布一个版本时，会有一个发布分支并以版本号命名。
104+
105+
在发布之后，我们会将发布分支的提交合并到主分支中。
106+
107+
当我们发现某个版本有bug时，我们会决定在以后的版本中修复它，或者在特定的hotfix版本中修复它。当我们决定修复hotfix版本时，我们会根据对应的release分支checkout hotfix分支，进行代码修复和验证，合并到develop分支和master分支。
108+
109+
对于较大的功能，我们将拉出功能分支进行开发和验证。
110+
111+
112+
### 提交规则
113+
114+
实际上，在 Higress 中，我们在提交时会认真对待两条规则：
115+
116+
* [提交消息](#提交消息)
117+
* [提交内容](#提交内容)
118+
119+
#### 提交消息
120+
121+
提交消息可以帮助审稿人更好地理解提交 PR 的目的是什么。它还可以帮助加快代码审查过程。我们鼓励贡献者使用显式的提交信息，而不是模糊的信息。一般来说，我们提倡以下提交消息类型：
122+
123+
* docs: xxxx. For example, "docs: add docs about Higress cluster installation".
124+
* feature: xxxx.For example, "feature: use higress config instead of istio config".
125+
* bugfix: xxxx. For example, "bugfix: fix panic when input nil parameter".
126+
* refactor: xxxx. For example, "refactor: simplify to make codes more readable".
127+
* test: xxx. For example, "test: add unit test case for func InsertIntoArray".
128+
* 其他可读和显式的表达方式。
129+
130+
另一方面，我们不鼓励贡献者通过以下方式提交消息：
131+
132+
* ~~修复错误~~
133+
* ~~更新~~
134+
* ~~添加文档~~
135+
136+
如果你不知道该怎么做，请参阅 [如何编写 Git 提交消息](http://chris.beams.io/posts/git-commit/) 作为开始。
137+
138+
#### 提交内容
139+
140+
提交内容表示一次提交中包含的所有内容更改。我们最好在一次提交中包含可以支持审阅者完整审查的内容，而无需任何其他提交的帮助。换句话说，一次提交中的内容可以通过 CI 以避免代码混乱。简而言之，我们需要牢记三个小规则：
141+
142+
* 避免在提交中进行非常大的更改；
143+
* 每次提交都完整且可审查。
144+
* 提交时检查 git config(`user.name`, `user.email`) 以确保它与您的 GitHub ID 相关联。
145+
146+
```bash
147+
git config --get user.name
148+
git config --get user.email
149+
```
150+
151+
* 提交pr时，请在'changes/'文件夹下的XXXmd文件中添加当前更改的简要说明
152+
153+
154+
另外，在代码变更部分，我们建议所有贡献者阅读Higress的 [代码风格](#代码风格)。
155+
156+
无论是提交信息，还是提交内容，我们都更加重视代码审查。
157+
158+
159+
### PR说明
160+
161+
PR 是更改 Higress 项目文件的唯一方法。为了帮助审查人更好地理解你的目的，PR 描述不能太详细。我们鼓励贡献者遵循 [PR 模板](./.github/PULL_REQUEST_TEMPLATE.md) 来完成拉取请求。
162+
163+
## 测试用例贡献
164+
165+
任何测试用例都会受到欢迎。目前，Higress 功能测试用例是高优先级的。
166+
167+
* 对于单元测试，您需要在同一模块的 test 目录中创建一个名为 xxxTest.go 的测试文件。
168+
169+
* 对于集成测试，您可以将集成测试放在 test 目录。
170+
//TBD
171+
172+
## 参与帮助任何事情
173+
174+
我们选择 GitHub 作为 Higress 协作的主要场所。所以Higress的最新更新总是在这里。尽管通过 PR 贡献是一种明确的帮助方式，但我们仍然呼吁其他方式。
175+
176+
* 如果可以的话，回复别人的问题；
177+
* 帮助解决其他用户的问题；
178+
* 帮助审查他人的 PR 设计；
179+
* 帮助审查其他人在 PR 中的代码；
180+
* 讨论 Higress 以使事情更清楚；
181+
* 在Github之外宣传Higress技术；
182+
* 写关于 Higress 的博客等等。
183+
184+
185+
## 代码风格
186+
//TBD
187+
总之，**任何帮助都是贡献。**

0 commit comments

Comments
 (0)