- [Engage to help anything](#Engage-to-help-anything)
- [参与任何形式的帮助](#参与任何形式的帮助)
- [发布版本](#发布版本)
- [联系我们](#联系我们)
@ -28,65 +28,62 @@
## 行为准则
#### Code and doc contribution
#### 代码与文档贡献
Every action to make project Open-IM-Server better is encouraged. On GitHub, every improvement for Open-IM-Server could be via a [PR](https://github.com/Open-IM-Server/pulls) (short for pull request).
+ 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!
+ 如果发现一个错误,尝试修复它!
+ 如果发现一个bug,尝试修复它!
+ 如果发现一些冗余的代码,尝试删除它们!
+ 如果发现缺少一些测试用例,尝试添加它们!
+ 如果可以增强一个功能,请不要犹豫!
+ 如果发现代码隐晦,尝试添加注释使其清晰!
+ 如果发现丑陋的代码,尝试重构它!
+ 如果可以帮助改进文档,那就更好不过了!
+ 如果发现文档不正确,请修复它!
+ ...
#### Where should I start?
#### 我应该从哪里开始
+ If you are new to the project, don't know how to contribute Open-IM-Server, please check out the [good first issue](https://github.com/OpenIMSDK/Open-IM-Server/issues?q=is%3Aopen+label%3A"good+first+issue"+sort%3Aupdated-desc) label.
+ You should be good at filtering the Open-IM-Server issue tags and finding the ones you like, such as [RFC](https://github.com/OpenIMSDK/Open-IM-Server/issues?q=is%3Aissue+is%3Aopen+RFC+label%3ARFC) for big initiatives, features for [feature](https://github.com/OpenIMSDK/Open-IM-Server/issues?q=is%3Aissue+label%3Afeature) proposals, and [bug](https://github.com/{github/issues?q=is%3Aissue+label%3Abug+) fixes.
+ If you are looking for something to work on, check out our [open issues](https://github.com/OpenIMSDK/Open-IM-Server/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc).
+ If you have an idea for a new feature, please [open an issue](https://github.com/OpenIMSDK/Open-IM-Server/issues/new/choose), and we can discuss it.
+ 如果您刚开始接触该项目,不知道如何为Open-IM-Server做出贡献,请查看 [good first issue](https://github.com/OpenIMSDK/Open-IM-Server/issues?q=is%3Aopen+label%3A"good+first+issue"+sort%3Aupdated-desc) 标签.
For any substantial design, there should be a well-crafted design document. This document is not just a simple record, but also a detailed description and manifestation, which can help team members better understand the design thinking and grasp the design direction. In the process of writing the design document, we can choose to use tools such as `Google Docs` or `Notion`, and even mark RFC in [issues](https://github.com/OpenIMSDK/Open-IM-Server/issues?q=is%3Aissue+is%3Aopen+RFC+label%3ARFC) or [discussions](https://github.com/OpenIMSDK/Open-IM-Server/discussions) for better collaboration. Of course, after completing the design document, we should also add it to our [Shared Drive](https://drive.google.com/drive/) and notify the appropriate working group to let everyone know of its existence. Only by doing so can we maximize the effectiveness of the design document and provide strong support for the smooth progress of the project.
Anybody can access the shared Drive for reading. To get access to comment. Once you've done that, head to the [shared Drive](https://drive.google.com/) and behold all the docs.
In addition to that, we'd love to invite you to [join our Slack](https://join.slack.com/t/openimsdk/shared_invite/zt-1tmoj26uf-_FDy3dowVHBiGvLk9e5Xkg) where you can play with your imagination, tell us what you're working on, and get a quick response.
When documenting a new design, we recommend a 2-step approach:
在记录新的设计时,我们建议采取两步方法:
1. 使用简短的RFC模板概述您的想法，并尽早获得反馈。
2. 一旦您获得足够的反馈和共识,您可以使用更长的设计文档模板更详细地指定和讨论您的设计。
1. Use the short-form RFC template to outline your ideas and get early feedback.
2. Once you have received sufficient feedback and consensus, you may use the longer-form design doc template to specify and discuss your design in more details.
为了向Open-IM-Server贡献功能,您需要遵循以下步骤:
In order to contribute a feature to Open-IM-Server you'll need to go through the following steps:
+ Discuss your idea with the appropriate [working groups](https://join.slack.com/t/openimsdk/shared_invite/zt-1tmoj26uf-_FDy3dowVHBiGvLk9e5Xkg) on the working group's Slack channel.
+ Once there is general agreement that the feature is useful, create a GitHub issue to track the discussion. The issue should include information about the requirements and use cases that it is trying to address.
+ Include a discussion of the proposed design and technical details of the implementation in the issue.
But keep in mind that there is no guarantee of it being accepted and so it is usually best to get agreement on the idea/design before time is spent coding it. However, sometimes seeing the exact code change can help focus discussions, so the choice is up to you.
To propose PR for the Open-IM-Server item, we assume you have registered a GitHub ID. Then you could finish the preparation in the following steps:
1. Fork the repository(Open-IM-Server)
2. **CLONE** your own repository to master locally. Use `git clone https://github.com/<your-username>/Open-IM-Server.git` to clone repository to your local machine. Then you can create new branches to finish the change you wish to make.
If you have developed multiple features in the same branch, you should create PR separately by rebasing to the main branch between each push:
如果您在同一分支中开发了多个功能，则应在每次推送之间对主分支进行rebase，并单独创建PR
```bash
# create new branch, for example git checkout -b feature/infra
@ -158,122 +155,120 @@ To propose PR for the Open-IM-Server item, we assume you have registered a GitHu
# then create pull request, and merge
```
7. **Open a pull request**to`OpenIMSDK/Open-IM-Server:main`
7. **Open a pull request**到`OpenIMSDK/Open-IM-Server:main`
It is recommended to review your changes before filing a pull request. Check if your code doesn't conflict with the main branch and no redundant code is included.
建议在提交拉取请求之前检查您的更改。检查您的代码是否与主分支冲突,并且未包含重复的代码。
## 风格和规范
We divide the problem into security and general problems:
我们将问题划分为安全问题和一般问题:
#### 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 Open-IM-Server, please do not discuss it in public and even do not open a public issue.
To be honest, we regard every user of Open-IM-Serveras a very kind contributor. After experiencing Open-IM-Server, you may have some feedback for the project. Then feel free to open an issue via [NEW ISSUE](https://github.com/OpenIMSDK/Open-IM-Server/issues/new/choose).
Since we collaborate project Open-IM-Server 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](https://github.com/OpenIMSDK/Open-IM-Server/tree/main/.github/ISSUE_TEMPLATE) for issue reporters. You can find three kinds of issue templates there: question, bug report and feature request. Please **BE SURE** to follow the instructions to fill fields in template.
**您可以在许多情况下打开问题:**
+ bug报告
+ 功能请求
+ Open-IM-Server性能问题
+ 功能建议
+ 功能设计
+ 需要帮助
+ 文档不完整
+ 测试改进
+ 关于Open-IM-Server项目的任何问题
+ 等等
**There are a lot of cases when you could open an issue:**
Also, we must be reminded when submitting a new question about Open-IM-Server, 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.
实际上在Open-IM-Server中,我们在提交时遵循两条规则:
#### Commit Rules
**🥇 提交消息:**
Actually in Open-IM-Server, we take two rules serious when committing:
Commit message could help reviewers better understand what the purpose of submitted PR is. 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:
We use [Semantic Commits](https://www.conventionalcommits.org/en/v1.0.0/) to make it easier to understand what a commit does and to build pretty changelogs. Please use the following prefixes for your commits:
+ `docs: xxxx`. For example, "docs: add docs about storage installation".
+ `feature: xxxx`.For example, "feature: make result show in sorted order".
+ `bugfix: xxxx`. For example, "bugfix: fix panic when input nil parameter".
+ `style: xxxx`. For example, "style: format the code style of Constants.java".
+ `refactor: xxxx.` For example, "refactor: simplify to make codes more readable".
+ `test: xxx`. For example, "test: add unit test case for func InsertIntoArray".
+ `chore: xxx.` For example, "chore: integrate travis-ci". It's the type of mantainance change.
+ 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~~
**🥈 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 two minor rules for us to keep in mind:
3. words are written in lowercase English, not uppercase English or other languages such as Chinese.
换句话说,一个单独提交中的内容可以通过CI以避免代码混乱。简而言之,我们要记住的两个小规则是:
No matter what the commit message, or commit content is, we do take more emphasis on code review.
1. 避免在一次提交中进行非常大的更改。
2. 每次提交都要完整且可审查。
3. 字词使用小写英语,而不是大写英语或其他语言(如中文)。
无论提交消息还是提交内容如何,我们都更加重视代码审查。
An example for this could be:
举个例子:
```bash
❯ git commit -a -s -m "docs: add a new section to the README"
```
#### PR Description
#### PR描述
PR is the only way to make change to Open-IM-Server project files. To help reviewers better get your purpose, PR description could not be too detailed. We encourage contributors to follow the [PR template](https://github.com/OpenIMSDK/Open-IM-Server/tree/main/.github/PULL_REQUEST_TEMPLATE.md) to finish the pull request.
You can find some very formal PR in [RFC](https://github.com/OpenIMSDK/Open-IM-Server/issues?q=is%3Aissue+is%3Aopen+RFC+label%3ARFC) issues and learn about them.
+ As long as you are working on your PR, please mark it as a draft
+ Please make sure that your PR is up-to-date with the latest changes in `main`
+ Mention the issue that your PR is addressing (Fix: #{ID_1}, #{ID_2})
+ Make sure that your PR passes all checks
+ 只要您正在处理PR,请将其标记为草稿。
+ 请确保您的PR与`main`的最新更改同步。
+ mention您的PR要解决的问题(Fix:#{ID_1},#{ID_2})。
+ 确保您的PR通过所有检查。
**🈴 Reviewing PRs:**
**🈴 审阅PR:**
+ Be respectful and constructive
+ Assign yourself to the PR
+ Check if all checks are passing
+ Suggest changes instead of simply commenting on found issues
+ If you are unsure about something, ask the author
+ If you are not sure if the changes work, try them out
+ Reach out to other reviewers if you are unsure about something
+ If you are happy with the changes, approve the PR
+ Merge the PR once it has all approvals and the checks are passing
+ 报错尊重、建设性的原则
+ 要尊重和建设性的
+ 将自己分配给 PR
+ 检查所有检查是否通过
+ 提出更改建议而不仅仅评论发现的问题。
+ 如果您对某些事情不确定,请向作者提问
+ 如果您不确定更改是否有效,请尝试更改
+ 如果您对某些事情不确定,请联系其他审阅人员
+ 如果您对更改感到满意,请批准 PR
+ 合并PR一次都有批准并通过检查
**⚠️ DCO check:**
**⚠️ DCO检测:**
We have a DCO check that runs on every pull request to ensure code quality and maintainability. This check verifies that the commit has been signed off, indicating that you have read and agreed to the provisions of the Developer Certificate of Origin. If you have not yet signed off on the commit, you can use the following command to sign off on the last commit you made:
Please note that signing off on a commit is a commitment that you have read and agreed to the provisions of the Developer Certificate of Origin. If you have not yet read this document, we strongly recommend that you take some time to read it carefully. If you have any questions about the content of this document, or if you need further assistance, please contact an administrator or relevant personnel.
+ [README.md](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/README.md): This file includes the basic information and instructions for getting started with Open-IM-Server.
+ [CONTRIBUTING.md](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/CONTRIBUTING.md): This file contains guidelines for contributing to Open-IM-Server's codebase, such as how to submit issues, pull requests, and code reviews.
+ [DEVELOPGUIDE.md](https://github.com/OpenIMSDK/Open-IM-Server/blob/main/DEVELOPGUIDE.md): This file provides a more in-depth guide to developing Open-IM-Server, including information on the project's architecture, coding conventions, and testing practices.
+ [Official Documentation](https://doc.rentsoft.cn/): This is the official documentation for Open-IM-Server, which includes comprehensive information on all of its features, configuration options, and troubleshooting tips.
请遵守以下规则以更好地格式化文档,这将极大地提高阅读体验。
Please obey the following rules to better format the docs, which would greatly improve the reading experience.
1. Please do not use Chinese punctuations in English docs, and vice versa.
2. Please use upper case letters where applicable, like the first letter of sentences / headings, etc.
3. Please specify a language for each Markdown code blocks, unless there's no associated languages.
4. Please insert a whitespace between Chinese and English words.
5. Please use the correct case for technical terms, such as using `HTTP` instead of http, `MySQL` rather than mysql, `Kubernetes` instead of kubernetes, etc.
6. Please check if there's any typos in the docs before submitting PRs.
We choose GitHub as the primary place for Open-IM-Server to collaborate. So the latest updates of Open-IM-Server are always here. Although contributions via PR is an explicit way to help, we still call for any other ways.
Releases of Open-IM-Server are done using [Release Please](https://github.com/googleapis/release-please) and [GoReleaser](https://goreleaser.com/). The workflow looks like this:
+ Release please is triggered, creates or updates a new release PR
+ This is done with every merge to main, the current release PR is updated every time
🎯 合并'velease please' PR到`main`:
🎯 Merging the 'release please' PR to `main`:
+ Release please被触发,根据提交消息创建新版本和更新更改日志
+ 触发GoReleaser,构建二进制文件和将其附加到版本
+ 创建容器并推送到容器注册表
+ Release please is triggered, creates a new release and updates the changelog based on the commit messages
+ GoReleaser is triggered, builds the binaries and attaches them to the release
+ Containers are created and pushed to the container registry
下一次相关合并,将创建新的发行版PR,然后过程重新开始。
With the next relevant merge, a new release PR will be created and the process starts again
**👀手动设置版本号：**
**👀 Manually setting the version:**
如果您想手动设置版本号,可以创建一个包含版本号的空提交消息的PR。举个例子:
If you want to manually set the version, you can create a PR with an empty commit message that contains the version number in the commit message. For example:
@ -347,15 +342,15 @@ Such a commit can get produced as follows:
## 联系我们
We value close connections with our users, developers, and contributors here at Open-IM-Server. With a large community and maintainer team, we're always here to help and support you. Whether you're looking to join our community or have any questions or suggestions, we welcome you to get in touch with us.
Our most recommended way to get in touch is through [Slack](https://join.slack.com/t/openimsdk/shared_invite/zt-1tmoj26uf-_FDy3dowVHBiGvLk9e5Xkg). Even if you're in China, Slack is usually not blocked by firewalls, making it an easy way to connect with us. Our Slack community is the ideal place to discuss and share ideas and suggestions with other users and developers of Open-IM-Server. You can ask technical questions, seek help, or share your experiences with other users of Open-IM-Server.
In addition to Slack, we also offer the following ways to get in touch:
除了Slack,我们还提供以下联系方式:
+ <ahref="https://join.slack.com/t/openimsdk/shared_invite/zt-1tmoj26uf-_FDy3dowVHBiGvLk9e5Xkg"target="_blank"><imgsrc="https://img.shields.io/badge/slack-%40OpenIMSDKCore-informational?logo=slack&style=flat-square"></a>: We also have Slack channels for you to communicate and discuss. To join, visit https://slack.com/ and join our [👀 Open-IM-Server slack](https://join.slack.com/t/openimsdk/shared_invite/zt-1tmoj26uf-_FDy3dowVHBiGvLk9e5Xkg) team channel.
+ <ahref="https://mail.google.com/mail/u/0/?fs=1&tf=cm&to=4closetool3@gmail.com"target="_blank"><imgsrc="https://img.shields.io/badge/gmail-%40OOpenIMSDKCore?style=social&logo=gmail"></a>: Get in touch with us on [Gmail](winxu81@gmail.com). If you have any questions or issues that need resolving, or any suggestions and feedback for our open source projects, please feel free to contact us via email.
+ <ahref="https://doc.rentsoft.cn/"target="_blank"><imgsrc="https://img.shields.io/badge/%E5%8D%9A%E5%AE%A2-%40OpenIMSDKCore-blue?style=social&logo=Octopus%20Deploy"></a>: Read our [blog](https://doc.rentsoft.cn/). Our blog is a great place to stay up-to-date with Open-IM-Server projects and trends. On the blog, we share our latest developments, tech trends, and other interesting information.
+ <ahref="https://github.com/OpenIMSDK/OpenIM-Docs/blob/main/docs/images/WechatIMG20.jpeg"target="_blank"><imgsrc="https://img.shields.io/badge/%E5%BE%AE%E4%BF%A1-OpenIMSDKCore-brightgreen?logo=wechat&style=flat-square"></a>: Add [Wechat](https://github.com/OpenIMSDK/OpenIM-Docs/blob/main/docs/images/WechatIMG20.jpeg) and indicate that you are a user or developer of Open-IM-Server. We will process your request as soon as possible.
SwardHorse
2 years ago
committed by
GitHub