diff --git a/src/en/guide/contribution/guideline/code_contribution.md b/src/en/guide/contribution/guideline/code_contribution.md index 24e8c93e..7ae0faf9 100644 --- a/src/en/guide/contribution/guideline/code_contribution.md +++ b/src/en/guide/contribution/guideline/code_contribution.md @@ -22,10 +22,19 @@ PR generally includes bug fixes and new feature submissions, and both need to be ### Before submission -Please ensure that all unit tests involved in existing code modifications can pass the self-test (such as executing `pytest tests/metagpt/environment/*`). -Please ensure that the newly added code file has a single test under the corresponding path and the self-test passes. +Please ensure that the unit tests involved in the modification of existing code or the new unit tests corresponding to the new code can pass the self-test. Please ensure that the submitted code has a complete `Google Docstring` description and procedural functional comments. +We use `pytest` for single testing. Before submitting, install `pytest` related dependency packages, update the unit test for the modified code or add a unit test for the newly added code. Generally, we expect the unit test file name to start with `test_` and be created using the same module path. For example: `role.py` implements role abstraction and is placed under `metagpt/roles/`. The corresponding unit test file should be `tests/metagpt/roles/test_role.py`. +In particular, for unit tests that require network access, such as `provider`, we recommend using the `mock` method to add it, which will not be affected by the network. A reference example is: `tests/metagpt/provider/test_qianfan_api.py`. + +```bash +pip3 install pytest==7.2.2 pytest-mock==3.11.1 pytest-asyncio==0.21.1 # Recommended +pytest tests # Example, execute all test files +pytest tests/metagpt/environment/* # Example, execute multiple test files +pytest tests/metagpt/environment/test_base_env.py # Example, execute a single test file +``` + Before committing, install `pre-commit` and use it to check the code specification to meet the submission conditions. The specific usage is as follows: ```bash @@ -55,10 +64,15 @@ After submission, the github-ci workflow will be used by default to check code s ## Issue Issue content can include bug feedback, description of new features expected to be supported, in-depth optimization of supported functions, etc. -Among them, new features, optimization items, etc. can be described based on your demand scenarios to provide sufficient context for further communication between the two parties. After submission, community staff will contact you and we will update it to ROADMAP after communication and confirmation. + +Among them, new features, optimization items, etc. can be described based on your demand scenarios to provide sufficient context for further communication between the two parties. After submission, community staff will contact you and we will update it to ROADMAP after communication and confirmation. We have added the `request_new_features` template by default. When submitting, you need to add the necessary information, including: + +- Feature description, Feature description. Required. +- Your Feature, Describes the motivation, idea, reference source or implementation process for implementing the Feature. Optional. + For bug feedback, in order to have enough problem context for analysis, the `show_me_the_bug` template is added by default. Necessary information needs to be added when submitting, including: -- Bug description Bug description. Required. -- Bug solved method Bug solution (if you know how to solve it). Optional. -- Environment information includes the large model type configuration used, system version, python version and some dependent package versions of the error stack. Required. -- Screenshots or logs On-site screenshots or logs corresponding to the bug. Required. +- Bug description, Bug description. Required. +- Bug solved method, Bug solution (if you know how to solve it). Optional. +- Environment information, includes the large model type configuration used, system version, python version, and some dependent package versions of the error stack. Required. +- Screenshots or logs, On-site screenshots or logs corresponding to the bug. Required. diff --git a/src/en/guide/contribution/rfc_sop.md b/src/en/guide/contribution/rfc_sop.md new file mode 100644 index 00000000..e011b66f --- /dev/null +++ b/src/en/guide/contribution/rfc_sop.md @@ -0,0 +1,87 @@ +# RFC SOP + +We directly use a subdirectory under [MetaGPT-docs](https://github.com/geekan/MetaGPT-docs) as the management repository for the RFC collection. The corresponding directory structure is + +```text +MetaGPT-docs +├── readme.md +├── src +│ ├── public +│ │ ├── image +│ │ │ ├── rfcs +│ │ │ │ ├── 001 # rfc number, to store figures and so on +│ │ │ │ └── 002 +│ ├── rfcs +│ │ ├── 001_20241010_agent_communication.md +│ │ └── 000_yyyymmdd_rfc_template.md # RFC writing template, named with number_submission-date_title +``` + +## Learn about RFC SOP + +### RFC Scope + +RFC is a change request, which is mainly used to describe new features or important functional updates of `MetaGPT`. It is output through `markdown` and stored in `MetaGPT-docs` to record the historical implementation functions of `MetaGPT`. Through these design document outputs and communication feedback, let the `MetaGPT` community participate. +The primary audience of RFC is the `MetaGPT` development community, which serves as a guide for functional design during development. The secondary audience is general users and developers who are interested in the starting point and implementation process of functional design. + +#### When to write an RFC + +As mentioned above, it is recommended to write an RFC in the following cases + +- When you see a feature to be implemented in the roadmap and want to make a functional design description for the feature implementation +- When you have a better understanding of `MetaGPT` and want to add some new features and explain your ideas +- When you have a better understanding of `MetaGPT` and found some changes and upgrades that are worth a larger scale of refactoring + +### Who is involved + +#### Creator + +The creator is the creator and main writer and maintainer of the RFC document. The creator outputs and updates the RFC template according to the expected functions. In the process, the creator updates the RFC according to the community feedback. + +#### Sponsor + +The sponsor is the main maintainer of the project, acting as a bridge between the creator and the review committee, and conducting relevant review organization work. + +Generally, the sponsor can also be the creator. + +#### Community staff + +Comment on the RFC document, including differences in design ideas, whether it meets the requirements, etc. The comments of community staff should be related to the RFC theme and give effective suggestions on the RFC content objectively. + +#### Review Committee + +The main maintainers of `MetaGPT` are composed of several core contributors in the community. Responsible for deciding whether to approve the RFC. + +- If there is a conflict in the document number, the review committee will come forward to coordinate and resolve it +- If there is a major dispute in the function design, the review committee will convene relevant personnel to discuss and determine the final conclusion + +## RFC merge process + +We follow the following process to manage RFCs + +- The creator can choose one of the core contributors of the project as the sponsor + +If the corresponding sponsor is not found within 2 weeks after the PR is released, the corresponding PR will be closed + +- Create your RFC request by using [fork and pull request](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) + +Refer to [RFC template](https://github.com/geekan/MetaGPT-docs/src/en/guide/contribution/xxx_yyyymmdd_rfc_template.md) and name the RFC file according to `xxx_yyyymmdd_rfc_title` (number_date_RFC title, xxx is the maximum number of the currently merged RFC + 1, yyyymmdd is the submission date, rfc_title is the rfc title, which should be as concise and short as possible). For example, if your RFC title is agent_communication, you can name it `001_20241010_agent_communication`. When you need to introduce images and other materials in the file, place them in the `src/public/image/rfcs/001` subfolder (001 is your RFC number). + +Fill in the basic information including creator, sponsor, update date, etc. in the front of the RFC file. + +- After the RFC PR is released, the sponsor needs to organize a relevant review meeting within **two weeks** to discuss the design and determine whether to merge it. If no consensus is reached, the creator needs to further explain the existing problems, and the sponsor determines the next review time (usually within **one week**). +- PRs that do not meet the standards or fail the review will be required to be modified or rejected, and passed PRs will be promoted in the community. + +## Maintain high standards + +RFC writing is not easy, we encourage and welcome contributors to write according to this standard. But at the same time we should ensure quality with a high standard. +When encountering the following situations, the RFC document needs to be extensively modified or rejected. + +- No sponsor organizes the corresponding review meeting +- Failure to reach a consensus on the design ideas during the review period +- Refusing to accept feedback generated during the review stage (including but not limited to compatibility, impact resolution, etc.) + +The RFC review process and the code review process are carried out independently. We will try our best to discuss it clearly in the design stage to reduce conflicts in the implementation process. + +## Acknowledgements + +This RFC SOP refers to the design of [tensorflow rfcs](https://github.com/tensorflow/community/tree/master/rfcs) to a certain extent, and we would like to express our gratitude. diff --git a/src/en/guide/contribution/rfc_template.md b/src/en/guide/contribution/rfc_template.md deleted file mode 100644 index d24a92ab..00000000 --- a/src/en/guide/contribution/rfc_template.md +++ /dev/null @@ -1 +0,0 @@ -Will be updated soon, stay tuned. diff --git a/src/en/guide/contribution/xxx_yyyymmdd_rfc_template.md b/src/en/guide/contribution/xxx_yyyymmdd_rfc_template.md new file mode 100644 index 00000000..806efd65 --- /dev/null +++ b/src/en/guide/contribution/xxx_yyyymmdd_rfc_template.md @@ -0,0 +1,84 @@ +# RFC Template + +Basic document information + +| Status | In progress, Under review, Merged | +| ----------- | ------------------------------------------------------------ | +| PR | PR url of this RFC | +| Creator | Username of the contributor who proposed this RFC | +| Initiator | Username of the maintainer who organized this RFC for review | +| Update date | Date of the most recent update to this document | + +# Background + +Provide information about the context and reasons for the creation of the RFC document. In this section, introduce the background of the issue, explain why this RFC was proposed, and the relevant history or technical developments. Explain the current challenges or needs. + +# Goals + +## Included + +Describe the scope of the RFC and what is included + +- Goal 1 +- Goal 2 + +## Excluded + +Specify what is not included or limited by the RFC + +- Non-Goal 1 +- Non-Goal 2 + +# Proposal + +This is the core content of the RFC, which contains detailed proposals and solutions. According to the actual situation, it is divided into different sub-headings to describe each aspect of the RFC proposal in detail and provide clear and specific information. + +### Design Introduction + +Introduce the overall design concept and principles of the proposal + +### Architecture Introduction + +Describe the system architecture of the RFC proposal in detail. You can draw a picture and give necessary text description of the picture + +### Module Introduction + +List and explain each module or component in the RFC proposal, and then give a detailed introduction, and explain how they interact with each other and how they interact with the outside world + +### Data Structure + +Describe the key data structures used in the proposal and explain the important fields. To improve readability + +### Process Introduction + +Describe the key processes in the RFC proposal, pictures and texts are best + +### Interface Introduction + +Introduce the various interfaces in the proposal, including interfaces between modules and external interfaces. It is recommended to provide a complete API description document link to match this document + +### Impact + +Record the impact that may be involved after the implementation of this RFC, including functions, performance efficiency, compatibility, user impact, etc. + +# Milestones [optional] + +List the key steps and timelines for implementing the RFC proposal, set specific goals and timelines for different stages of implementing the proposal, so as to track and evaluate progress + +# FAQ + +Write possible questions and answers for readers + +# Appendix [optional] + +## Terminology + +| Terminology | Full Name | Explanation | +| ----------- | --------- | ----------- | +| | | | +| | | | +| | | | +| | | | +| | | | + +## References diff --git a/src/zh/guide/contribution/guideline/code_contribution.md b/src/zh/guide/contribution/guideline/code_contribution.md index be49fce6..38d7cb0c 100644 --- a/src/zh/guide/contribution/guideline/code_contribution.md +++ b/src/zh/guide/contribution/guideline/code_contribution.md @@ -22,10 +22,19 @@ PR一般包括bug修复和新功能提交,都需要尽可能按下述流程规 ### 提交前 -请确保对已有代码修改涉及到的单测都能自测通过(比如执行`pytest tests/metagpt/environment/*`)。 -请确保新增加的代码文件有对应路径下的单测且自测通过。 +请确保对已有代码修改涉及到的单测或新增代码对应的新增单测可以自测通过。 请确保提交的代码有完整的`Google Docstring`说明和过程功能注释。 +我们使用`pytest`进行单测试下。在提交前,安装`pytest`相关依赖包,对修改的代码更新单测或新增的代码增加单测。一般的,我们期望单测文件名以`test_`为开头,并且使用相同的模块路径进行创建,例如:`role.py`实现了角色抽象,并放置在`metagpt/roles/`下,对应的单测文件应该为`tests/metagpt/roles/test_role.py`。 +特别的,对于需要进行网络访问的单测,比如`provider`,我们建议使用`mock`方式进行添加,不会收到网络的影响。一个可参考的例子是:`tests/metagpt/provider/test_qianfan_api.py`。 + +```bash +pip3 install pytest==7.2.2 pytest-mock==3.11.1 pytest-asyncio==0.21.1 # 推荐的 +pytest tests # 示例,执行全部单测文件 +pytest tests/metagpt/environment/* # 示例,执行多个单测文件 +pytest tests/metagpt/environment/test_base_env.py # 示例,执行单个单测文件 +``` + 在提交前,安装`pre-commit`,并使用其对代码规范进行检查以符合提交条件。具体使用如下: ```bash @@ -54,11 +63,16 @@ pre-commit run --all-files # 或检查个别文件 pre-commit run --files meta ## Issue提交 -Issue的内容可以包括Bug反馈、期望支持新特性描述、已支持功能的深度优化等。 -其中,对于新特性、优化项等,可以针对你的需求场景展开描述,为双方进一步沟通提供足够的上下文。提交后,将会有社区工作人员联系,沟通确认后我们也会更新到ROADMAP中。 +Issue的内容可以包括Bug反馈、期望支持新特性描述、已支持功能的深度优化等。 + +其中,对于新特性、优化项等,可以针对你的需求场景展开描述,为双方进一步沟通提供足够的上下文。提交后,将会有社区工作人员联系,沟通确认后我们也会更新到ROADMAP中。我们默认添加了`request_new_features`模板,提交时需要补充必要的信息,包括: + +- Feature description,Feature描述。必填。 +- Your Feature,描述实现Feature的动机、想法、参考来源或实现过程。选填。 + 对于Bug反馈,为了有足够的问题上下文进行分析,默认添加了`show_me_the_bug`模版,提交时需要补充必要的信息,包括: -- Bug description Bug描述。必填。 -- Bug solved method Bug解决方式(如果你知道如何解决)。选填。 -- Environment information 包括使用的大模型类型配置、系统版本、python版本及错误堆栈的部分依赖包版本。必填。 -- Screenshots or logs Bug对应的现场截图或日志。必填。 +- Bug description,Bug描述。必填。 +- Bug solved method,Bug解决方式(如果你知道如何解决)。选填。 +- Environment information,包括使用的大模型类型配置、系统版本、python版本及错误堆栈的部分依赖包版本。必填。 +- Screenshots or logs,Bug对应的现场截图或日志。必填。 diff --git a/src/zh/guide/contribution/rfc_sop.md b/src/zh/guide/contribution/rfc_sop.md new file mode 100644 index 00000000..e6719627 --- /dev/null +++ b/src/zh/guide/contribution/rfc_sop.md @@ -0,0 +1,86 @@ +# RFC SOP + +我们直接使用 [MetaGPT-docs](https://github.com/geekan/MetaGPT-docs) 下的一个子目录作为RFC集合的管理仓库,对应的目录结构为 + +```text +MetaGPT-docs +├── readme.md +├── src +│ ├── public +│ │ ├── image +│ │ │ ├── rfcs +│ │ │ │ ├── 001 # rfc number, to store figures and so on +│ │ │ │ └── 002 +│ ├── rfcs +│ │ ├── 001_20241010_agent_communication.md +│ │ └── 000_yyyymmdd_rfc_template.md # RFC撰写模板,以编号_提交日期_标题命名 +``` + +## 了解 RFC SOP + +### RFC 适用范围 + +RFC是变更请求,主要用于描述`MetaGPT`的新特性或重要功能更新。通过`markdown`进行输出,并存储于`MetaGPT-docs`中,记录`MetaGPT`的历史实现功能。通过这些设计文档输出与交流反馈,让`MetaGPT`社区参与其中。 +RFC的主要受众是`MetaGPT`开发社区,作为开发期间功能设计的指导指南。次要受众是功能设计出发点和实现过程感兴趣的一般用户和开发人员。 + +#### 什么情况下需要写一个RFC + +正如前面所提到的,在符合下述情况下,建议进行RFC的输出 + +- 当你看到路线图中的待实现特性,并期望就该特性实现做一个功能设计说明时 +- 当你比较了解`MetaGPT`后,期望添加一些新特性并阐述你的想法时 +- 当你比较了解`MetaGPT`并从中发现了一些值得比较大范围的重构改动升级时 + +### 谁参与其中 + +#### 创建者 + +创建者是RFC文档的创建者和主要编写、维护者,针对期望实现的功能按RFC模版进行输出和更新。并在过程中,针对社区的反馈进行更新。 + +#### 发起者 + +发起者是项目的主要维护者,起到创建者与评审委员会的桥梁作用,进行相关的评审组织工作。 +一般的,发起者也可以是创建者。 + +#### 社区人员 + +针对RFC文档进行评论,包括设计思路差异、是否满足需求等。社区人员的评论应围绕RFC主题相关,客观的对RFC内容给予有效的建议。 + +#### 评审委员会 + +`MetaGPT`的主要维护者,由社区多位核心贡献者组成。负责决定是否批准RFC。 + +- 如果存在文档编号冲突,评审委员会人员将出面进行协调解决 +- 如果功能设计存在较大的争议,评审委员会将召集相关人员进行讨论并确定最终结论 + +## RFC 合入流程 + +我们遵循下述流程进行RFC的管理 + +- 创建者可以在项目的核心贡献者中选择一位作为发起者 + + 如果在PR发布后的2个星期内没找到对应的发起者,对应PR将会被关闭 + +- 通过使用 [fork and pull request](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) 的方式创建你的RFC请求 + + 参考[RFC模版](https://github.com/geekan/MetaGPT-docs/src/zh/guide/contribution/xxx_yyyymmdd_rfc_template.md) 按照`xxx_yyyymmdd_rfc_title`(编号\_日期\_RFC标题,xxx为当前已合入RFC最大编号值+1,yyyymmdd为提交日期,rfc_title为rfc标题,需尽量精练简短)进行RFC文件命名。例如,如果你的RFC标题为agent_communication,你可以命名为`001_20241010_agent_communication`。在文件中需要引入图片等素材时,将其放置到`src/public/image/rfcs/001`子文件夹下(001为你的RFC编号)。 + + 在RFC文件的前文填写包括创建者、发起者、更新日期等基础信息。 + +- RFC PR发布后,发起者需要在**两周内**组织相关的评审会,针对设计展开讨论并确定是否合入。如果未能达成共识,创建者需针对存在问题展开进一步说明,发起者确定下一次的评审时间(一般在**一周内**)。 +- 不符合标准或评审未通过的PR将被要求进行修改或拒绝,通过的PR将会在社区进行推广。 + +## 保持高标准 + +RFC 撰写不易,我们鼓励和欢迎贡献者能够按该标准撰写。但同时我们应该以一个较高的标准来保证质量。 +当碰到下述情况时,RFC文档需要进行大范围的修改或被拒绝合入。 + +- 没有发起者组织对应的评审会 +- 评审期间未能就设计思路达成共识 +- 拒绝接受评审阶段产生的反馈意见(包括但不局限于兼容性、影响面解决等) + +RFC的评审过程和代码的评审过程是独立进行的,我们将尽可能在设计阶段讨论清楚,减少实现过程中的冲突。 + +## 致谢 + +本 RFC SOP在一定程度上参考了[tensorflow rfcs](https://github.com/tensorflow/community/tree/master/rfcs) 的设计,在此表示感谢。 diff --git a/src/zh/guide/contribution/rfc_template.md b/src/zh/guide/contribution/rfc_template.md deleted file mode 100644 index d3ac750e..00000000 --- a/src/zh/guide/contribution/rfc_template.md +++ /dev/null @@ -1,51 +0,0 @@ -# 开发者RFC模版 - -文档修改历史 - -| 日期 | 版本 | 作者 | 修改内容 | -| ---------- | ------ | ---- | -------- | -| 2023/09/13 | v0.0.1 | | 初版 | -| | | | | - -本文档评审记录 - -| 审核人 | 邀请日期 | 审核日期 | 审核意见 | -| ------ | ---------- | -------- | -------- | -| @xxx | 2023/09/13 | | | -| | | | | - -# 背景 - -# 目标 - -## 定义 - -### 包括的 - -### 不包括的 - -## 有则更优 - -# 提案 - -3.1 - -3.2 - -# 里程碑[可选] - -# 开放讨论 - -# 附录[可选] - -## 术语 - -| 术语 | 全称 | 解释 | -| ---- | ---- | ---- | -| | | | -| | | | -| | | | -| | | | -| | | | - -## 参考 diff --git a/src/zh/guide/contribution/xxx_yyyymmdd_rfc_template.md b/src/zh/guide/contribution/xxx_yyyymmdd_rfc_template.md new file mode 100644 index 00000000..509d2c5f --- /dev/null +++ b/src/zh/guide/contribution/xxx_yyyymmdd_rfc_template.md @@ -0,0 +1,84 @@ +# RFC 模版 + +文档基本信息 + +| 状态 | 进行中,评审中,已合入 | +| -------- | ------------------------------- | +| PR | 该RFC的 PR url | +| 创建者 | 提出本RFC的贡献者用户名 | +| 发起者 | 组织该RFC进行评审的维护者用户名 | +| 更新日期 | 最近更新本文档的日期 | + +# 背景 + +提供关于RFC文档产生的上下文和原因的信息,在这一部分,介绍问题的背景,说明为何提出这个RFC,以及相关的历史或技术发展。阐明当前的挑战或需求。 + +# 目标 + +## 包括的 + +描述RFC目标的范围和包含的内容 + +- 目标1 +- 目标2 + +## 不包括的 + +明确RFC不包括的内容或限制 + +- 非目标1 +- 非目标2 + +# 提案 + +这是RFC的核心内容,包含详细的提案和解决方案,根据实际情况,拆分成不同的子标题来详细描述RFC提案的各个方面,提供清晰、具体的信息。 + +### 设计介绍 + +介绍提案的整体设计理念和原则 + +### 架构介绍 + +详细描述RFC提案的系统架构,可画图并对图作必要的文字描述 + +### 模块介绍 + +列举并解释RFC提案中的各个模块或组件,然后进行详细的介绍,并对他们之间如何交互,与外界如何交互进行说明 + +### 数据结构 + +说明在提案中使用的关键数据结构,并对重要字段做解释。为提高可读性 + +### 流程介绍 + +描述RFC提案中的关键流程,图文最佳 + +### 接口介绍 + +介绍提案中的各种接口,包括模块之间的接口和外部接口,建议提供完整的 API 描述文档链接以搭配本文档 + +### 影响 + +记录本RFC实现后可能会涉及到的影响,包括功能、性能效率、兼容性、用户影响等等 + +# 里程碑[可选] + +列出实现RFC提案的关键步骤和时间表,为实施提案的不同阶段设定具体的目标和时间表,以便跟踪和评估进度 + +# FAQ + +撰写读者可能的问题与回答 + +# 附录[可选] + +## 术语 + +| 术语 | 全称 | 解释 | +| ---- | ---- | ---- | +| | | | +| | | | +| | | | +| | | | +| | | | + +## 参考