From 294c26735b4d54342bfec698d8305fc932479769 Mon Sep 17 00:00:00 2001 From: jimin Date: Mon, 7 Nov 2022 16:49:12 +0800 Subject: [PATCH] optimize: add contributing docs (#35) --- .licenserc.yaml | 3 +- CODE_OF_CONDUCT.md | 76 ++++++++++++++++++ CONTRIBUTING_CN.md | 187 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING_EN.md | 187 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 451 insertions(+), 2 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING_CN.md create mode 100644 CONTRIBUTING_EN.md diff --git a/.licenserc.yaml b/.licenserc.yaml index 5c10371b5e..15d856ffa0 100644 --- a/.licenserc.yaml +++ b/.licenserc.yaml @@ -5,8 +5,7 @@ header: paths-ignore: - '.gitignore' - - 'README.md' - - 'README_EN.md' + - '*.md' - 'LICENSE' - '.github/**' - '.licenserc.yaml' diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..d6b6be2902 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at higress@googlegroups.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md new file mode 100644 index 0000000000..ddefaede29 --- /dev/null +++ b/CONTRIBUTING_CN.md @@ -0,0 +1,187 @@ +# 为 Higress 做贡献 + +如果你有兴趣寻找关于Higress的漏洞，我们会热烈欢迎。首先，我们非常鼓励这种意愿。这是为您提供的贡献指南列表。 + +[[English Contributing Document](./CONTRIBUTING_EN.md)] + +## 话题 + +* [报告安全问题](#报告安全问题) +* [报告一般问题](#报告一般问题) +* [代码和文档贡献](#代码和文档贡献) +* [测试用例贡献](#测试用例贡献) +* [参与帮助任何事情](#参与帮助任何事情) +* [代码风格](#代码风格) + +## 报告安全问题 + +安全问题总是得到认真对待。作为我们通常的原则，我们不鼓励任何人传播安全问题。如果您发现Higress的安全问题，请不要公开讨论，甚至不要公开问题。相反，我们鼓励您向 [higress@googlegroups.com](mailto:higress@googlegroups.com) 发送私人电子邮件 以报告此情况。 + +## 报告一般问题 + +老实说，我们把每一个 Higress 用户都视为非常善良的贡献者。在体验了 Higress 之后，您可能会对项目有一些反馈。然后随时通过 [NEW ISSUE](https://github. com/alibaba/higress/issues/new/choose)打开一个问题。 + +因为我们在一个分布式的方式合作项目Higress，我们欣赏写得很好的，详细的，准确的问题报告。为了让沟通更高效，我们希望每个人都可以搜索您的问题是否在搜索列表中。如果您发现它存在，请在现有问题下的评论中添加您的详细信息，而不是打开一个全新的问题。 + +为了使问题细节尽可能标准，我们为问题报告者设置了一个[问题模板](./.github/ISSUE_TEMPLATE) 请务必按照说明填写模板中的字段。 + +有很多情况你可以打开一个问题： + +* 错误报告 +* 功能要求 +* 性能问题 +* 功能提案 +* 功能设计 +* 需要帮助 +* 文档不完整 +* 测试改进 +* 关于项目的任何问题 +* 等等 + +另外我们必须提醒的是，在填写新问题时，请记住从您的帖子中删除敏感数据。敏感数据可能是密码、密钥、网络位置、私人业务数据等。 + +## 代码和文档贡献 + +鼓励采取一切措施使 Higress 项目变得更好。在 GitHub 上，Higress 的每项改进都可以通过 PR（Pull Request的缩写）实现。 + +* 如果您发现错别字，请尝试修复它！ +* 如果您发现错误，请尝试修复它！ +* 如果您发现一些多余的代码，请尝试删除它们！ +* 如果您发现缺少一些测试用例，请尝试添加它们！ +* 如果您可以增强功能，请**不要**犹豫！ +* 如果您发现代码晦涩难懂，请尝试添加注释以使其更加易读！ +* 如果您发现代码丑陋，请尝试重构它！ +* 如果您能帮助改进文档，那就再好不过了！ +* 如果您发现文档不正确，只需执行并修复它！ +* ... + +实际上不可能完整地列出它们。记住一个原则： + +> 我们期待您的任何PR。 + +由于您已准备好通过 PR 改进 Higress，我们建议您可以在此处查看 PR 规则。 + +* [工作区准备](#工作区准备) +* [分支定义](#分支定义) +* [提交规则](#提交规则) +* [PR说明](#PR说明) + +### 工作区准备 + +为了提出 PR，我们假设你已经注册了一个 GitHub ID。然后您可以通过以下步骤完成准备工作： + +1. **FORK** Higress 到您的存储库。要完成这项工作，您只需单击 [alibaba/higress](https://github.com/alibaba/higress) 主页右侧的 Fork 按钮。然后你将在 + 中得到你的存储库`https://github.com//higress`，其中your-username是你的 GitHub 用户名。 + +2. **克隆** 您自己的存储库以在本地开发. 用于 `git clone git@github.com:/higress.git` 将存储库克隆到本地计算机。 然后您可以创建新分支来完成您希望进行的更改。 + +3. **设置远程** 将上游设置为 `git@github.com:alibaba/higress.git` 使用以下两个命令： + +```bash +git remote add upstream git@github.com:alibaba/higress.git +git remote set-url --push upstream no-pushing +``` + +使用此远程设置，您可以像这样检查您的 git 远程配置： + +```shell +$ git remote -v +origin git@github.com:/higress.git (fetch) +origin git@github.com:/higress.git (push) +upstream git@github.com:alibaba/higress.git (fetch) +upstream no-pushing (push) +``` + +添加这个，我们可以轻松地将本地分支与上游分支同步。 + +### 分支定义 + +现在我们假设通过拉取请求的每个贡献都是针对Higress 中的 [开发分支](https://github.com/alibaba/higress/tree/develop) 。在贡献之前，请注意分支定义会很有帮助。 + +作为贡献者，请再次记住，通过拉取请求的每个贡献都是针对分支开发的。而在Higress项目中，还有其他几个分支，我们一般称它们为release分支（如0.6.0、0.6.1）、feature分支、hotfix分支和master分支。 + +当正式发布一个版本时，会有一个发布分支并以版本号命名。 + +在发布之后，我们会将发布分支的提交合并到主分支中。 + +当我们发现某个版本有bug时，我们会决定在以后的版本中修复它，或者在特定的hotfix版本中修复它。当我们决定修复hotfix版本时，我们会根据对应的release分支checkout hotfix分支，进行代码修复和验证，合并到develop分支和master分支。 + +对于较大的功能，我们将拉出功能分支进行开发和验证。 + + +### 提交规则 + +实际上，在 Higress 中，我们在提交时会认真对待两条规则： + +* [提交消息](#提交消息) +* [提交内容](#提交内容) + +#### 提交消息 + +提交消息可以帮助审稿人更好地理解提交 PR 的目的是什么。它还可以帮助加快代码审查过程。我们鼓励贡献者使用显式的提交信息，而不是模糊的信息。一般来说，我们提倡以下提交消息类型： + +* docs: xxxx. For example, "docs: add docs about Higress cluster installation". +* feature: xxxx.For example, "feature: use higress config instead of istio config". +* bugfix: xxxx. For example, "bugfix: fix panic when input nil parameter". +* refactor: xxxx. For example, "refactor: simplify to make codes more readable". +* test: xxx. For example, "test: add unit test case for func InsertIntoArray". +* 其他可读和显式的表达方式。 + +另一方面，我们不鼓励贡献者通过以下方式提交消息： + +* ~~修复错误~~ +* ~~更新~~ +* ~~添加文档~~ + +如果你不知道该怎么做，请参阅 [如何编写 Git 提交消息](http://chris.beams.io/posts/git-commit/) 作为开始。 + +#### 提交内容 + +提交内容表示一次提交中包含的所有内容更改。我们最好在一次提交中包含可以支持审阅者完整审查的内容，而无需任何其他提交的帮助。换句话说，一次提交中的内容可以通过 CI 以避免代码混乱。简而言之，我们需要牢记三个小规则： + +* 避免在提交中进行非常大的更改； +* 每次提交都完整且可审查。 +* 提交时检查 git config(`user.name`, `user.email`) 以确保它与您的 GitHub ID 相关联。 + +```bash +git config --get user.name +git config --get user.email +``` + +* 提交pr时，请在'changes/'文件夹下的XXXmd文件中添加当前更改的简要说明 + + +另外，在代码变更部分，我们建议所有贡献者阅读Higress的 [代码风格](#代码风格)。 + +无论是提交信息，还是提交内容，我们都更加重视代码审查。 + + +### PR说明 + +PR 是更改 Higress 项目文件的唯一方法。为了帮助审查人更好地理解你的目的，PR 描述不能太详细。我们鼓励贡献者遵循 [PR 模板](./.github/PULL_REQUEST_TEMPLATE.md) 来完成拉取请求。 + +## 测试用例贡献 + +任何测试用例都会受到欢迎。目前，Higress 功能测试用例是高优先级的。 + +* 对于单元测试，您需要在同一模块的 test 目录中创建一个名为 xxxTest.go 的测试文件。 + +* 对于集成测试，您可以将集成测试放在 test 目录。 +//TBD + +## 参与帮助任何事情 + +我们选择 GitHub 作为 Higress 协作的主要场所。所以Higress的最新更新总是在这里。尽管通过 PR 贡献是一种明确的帮助方式，但我们仍然呼吁其他方式。 + +* 如果可以的话，回复别人的问题； +* 帮助解决其他用户的问题； +* 帮助审查他人的 PR 设计； +* 帮助审查其他人在 PR 中的代码； +* 讨论 Higress 以使事情更清楚； +* 在Github之外宣传Higress技术； +* 写关于 Higress 的博客等等。 + + +## 代码风格 +//TBD +总之，**任何帮助都是贡献。** diff --git a/CONTRIBUTING_EN.md b/CONTRIBUTING_EN.md new file mode 100644 index 0000000000..2a3ed3a9d0 --- /dev/null +++ b/CONTRIBUTING_EN.md @@ -0,0 +1,187 @@ +# Contributing to Higress + +It is warmly welcomed if you have interest to hack on Higress. First, we encourage this kind of willing very much. And here is a list of contributing guide for you. + +[[中文贡献文档](./CONTRIBUTING_CN.md)] + +## Topics + +* [Reporting security issues](#reporting-security-issues) +* [Reporting general issues](#reporting-general-issues) +* [Code and doc contribution](#code-and-doc-contribution) +* [Test case contribution](#test-case-contribution) +* [Engage to help anything](#engage-to-help-anything) +* [Code Style](#code-style) + +## Reporting security issues + +Security issues are always treated seriously. As our usual principle, we discourage anyone to spread security issues. If you find a security issue of Higress, please do not discuss it in public and even do not open a public issue. Instead we encourage you to send us a private email to [higress@googlegroups.com](mailto:higress@googlegroups.com) to report this. + +## Reporting general issues + +To be honest, we regard every user of Higress as a very kind contributor. After experiencing Higress, you may have +some feedback for the project. Then feel free to open an issue via [NEW ISSUE](https://github. +com/alibaba/higress/issues/new/choose). + +Since we collaborate project Higress in a distributed way, we appreciate **WELL-WRITTEN**, **DETAILED**, **EXPLICIT** issue reports. To make the communication more efficient, we wish everyone could search if your issue is an existing one in the searching list. If you find it existing, please add your details in comments under the existing issue instead of opening a brand new one. + +To make the issue details as standard as possible, we setup an [ISSUE TEMPLATE](./.github/ISSUE_TEMPLATE) for issue reporters. Please **BE SURE** to follow the instructions to fill fields in template. + +There are a lot of cases when you could open an issue: + +* bug report +* feature request +* performance issues +* feature proposal +* feature design +* help wanted +* doc incomplete +* test improvement +* any questions on project +* and so on + +Also we must remind that when filling a new issue, please remember to remove the sensitive data from your post. Sensitive data could be password, secret key, network locations, private business data and so on. + +## Code and doc contribution + +Every action to make project Higress better is encouraged. On GitHub, every improvement for Higress could be via a PR (short for pull request). + +* If you find a typo, try to fix it! +* If you find a bug, try to fix it! +* If you find some redundant codes, try to remove them! +* If you find some test cases missing, try to add them! +* If you could enhance a feature, please **DO NOT** hesitate! +* If you find code implicit, try to add comments to make it clear! +* If you find code ugly, try to refactor that! +* If you can help to improve documents, it could not be better! +* If you find document incorrect, just do it and fix that! +* ... + +Actually it is impossible to list them completely. Just remember one principle: + +> WE ARE LOOKING FORWARD TO ANY PR FROM YOU. + +Since you are ready to improve Higress with a PR, we suggest you could take a look at the PR rules here. + +* [Workspace Preparation](#workspace-preparation) +* [Branch Definition](#branch-definition) +* [Commit Rules](#commit-rules) +* [PR Description](#pr-description) + +### Workspace Preparation + +To put forward a PR, we assume you have registered a GitHub ID. Then you could finish the preparation in the following steps: + +1. **FORK** Higress to your repository. To make this work, you just need to click the button Fork in right-left of[alibaba/higress](https://github.com/alibaba/higress) main page. Then you will end up with your repository in + `https://github.com//higress`, in which `your-username` is your GitHub username. + +1. **CLONE** your own repository to develop locally. Use `git clone git@github.com:/higress.git` to clone repository to your local machine. Then you can create new branches to finish the change you wish to make. + +1. **Set Remote** upstream to be `git@github.com:alibaba/higress.git` using the following two commands: + +```bash +git remote add upstream git@github.com:alibaba/higress.git +git remote set-url --push upstream no-pushing +``` + +With this remote setting, you can check your git remote configuration like this: + +```shell +$ git remote -v +origin git@github.com:/higress.git (fetch) +origin git@github.com:/higress.git (push) +upstream git@github.com:alibaba/higress.git (fetch) +upstream no-pushing (push) +``` + +Adding this, we can easily synchronize local branches with upstream branches. + +### Branch Definition + +Right now we assume every contribution via pull request is for [branch develop](https://github.com/alibaba/higress/tree/develop) in Higress. Before contributing, be aware of branch definition would help a lot. + +As a contributor, keep in mind again that every contribution via pull request is for branch develop. While in project Higress, there are several other branches, we generally call them release branches(such as 0.6.0,0.6.1), feature branches, hotfix branches and master branch. + +When officially releasing a version, there will be a release branch and named with the version number. + +After the release, we will merge the commit of the release branch into the master branch. + +When we find that there is a bug in a certain version, we will decide to fix it in a later version or fix it in a specific hotfix version. When we decide to fix the hotfix version, we will checkout the hotfix branch based on the corresponding release branch, perform code repair and verification, and merge it into the develop branch and the master branch. + +For larger features, we will pull out the feature branch for development and verification. + + +### Commit Rules + +Actually in Higress, we take two rules serious when committing: + +* [Commit Message](#commit-message) +* [Commit Content](#commit-content) + +#### Commit Message + +Commit message could help reviewers better understand what is the purpose of submitted PR. It could help accelerate the code review procedure as well. We encourage contributors to use **EXPLICIT** commit message rather than ambiguous message. In general, we advocate the following commit message type: + +* docs: xxxx. For example, "docs: add docs about Higress cluster installation". +* feature: xxxx.For example, "feature: use higress config instead of istio config". +* bugfix: xxxx. For example, "bugfix: fix panic when input nil parameter". +* refactor: xxxx. For example, "refactor: simplify to make codes more readable". +* test: xxx. For example, "test: add unit test case for func InsertIntoArray". +* other readable and explicit expression ways. + +On the other side, we discourage contributors from committing message like the following ways: + +* ~~fix bug~~ +* ~~update~~ +* ~~add doc~~ + +If you get lost, please see [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/) for a start. + +#### Commit Content + +Commit content represents all content changes included in one commit. We had better include things in one single commit which could support reviewer's complete review without any other commits' help. In another word, contents in one single commit can pass the CI to avoid code mess. In brief, there are three minor rules for us to keep in mind: + +* avoid very large change in a commit; +* complete and reviewable for each commit. +* check git config(`user.name`, `user.email`) when committing to ensure that it is associated with your GitHub ID. + +```bash +git config --get user.name +git config --get user.email +``` + +* when submitting pr, please add a brief description of the current changes to the X.X.X.md file under the 'changes/' folder + + +In addition, in the code change part, we suggest that all contributors should read the [code style of Higress](#code-style). + +No matter commit message, or commit content, we do take more emphasis on code review. + + +### PR Description + +PR is the only way to make change to Higress project files. To help reviewers better get your purpose, PR description could not be too detailed. We encourage contributors to follow the [PR template](./.github/PULL_REQUEST_TEMPLATE.md) to finish the pull request. + +## Test case contribution + +Any test case would be welcomed. Currently, Higress function test cases are high priority. + +* For unit test, you need to create a test file named `xxxTest.go` in the test directory of the same module. +* For integration test, you can put the integration test in the test directory. +//TBD +## Engage to help anything + +We choose GitHub as the primary place for Higress to collaborate. So the latest updates of Higress are always here. Although contributions via PR is an explicit way to help, we still call for any other ways. + +* reply to other's issues if you could; +* help solve other user's problems; +* help review other's PR design; +* help review other's codes in PR; +* discuss about Higress to make things clearer; +* advocate Higress technology beyond GitHub; +* write blogs on Higress and so on. + + +## Code Style +//TBD +In a word, **ANY HELP IS CONTRIBUTION.**