Merge pull request #164 from better629/main

add rfc sop/template and update contribution

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.

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.

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

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对应的现场截图或日志。必填。