OASIS代码贡献指南：从issue到PR的完整流程

【免费下载链接】oasis 🏝️ OASIS: Open Agent Social Interaction Simulations with One Million Agents. 项目地址: https://gitcode.com/gh_mirrors/oasis2/oasis

OASIS（Open Agent Social Interaction Simulations with One Million Agents）是一个开源项目，旨在提供大规模智能体社交互动模拟平台。本指南将详细介绍从发现问题到提交PR的完整贡献流程，帮助新手开发者快速参与到OASIS项目中。

1. 准备工作：环境搭建与社区加入

1.1 项目克隆与依赖安装

首先需要将项目代码克隆到本地环境：

git clone https://gitcode.com/gh_mirrors/oasis2/oasis
cd oasis
poetry install
eval $(poetry env activate)
pre-commit install

这些命令会安装所有必要的依赖项，创建虚拟环境并配置代码提交检查工具。

1.2 加入社区交流

OASIS拥有活跃的开发者社区，建议通过以下渠道加入交流：

• Discord：通过官方邀请链接加入
• 微信群：扫描项目中的assets/wechatgroup.png二维码

定期参与社区会议可以了解项目最新动态和开发方向，中文开发者会议时间为每周四晚上10点（UTC+8）。

2. 贡献流程：从Issue到PR的详细步骤

2.1 发现与认领Issue

项目的所有待解决问题都在GitHub Issues页面跟踪。新手可以通过以下步骤开始：

1. 浏览issues页面，寻找感兴趣的问题
2. 使用标签（如"good first issue"）筛选适合新手的任务
3. 认领问题：直接分配给自己或在评论区留言表示正在处理

OASIS架构展示了用户智能体与环境互动的核心机制

2.2 代码开发规范

在开始编码前，请了解并遵循项目的开发规范：

• 命名原则：避免使用缩写，采用清晰描述性命名（如使用message_window_size而非msg_win_sz）
• 日志规范：使用logger模块而非print语句输出信息
• 文档要求：所有类和方法都需要编写详细的文档字符串（docstring）

文档字符串应使用原始字符串格式r"""，包含功能描述、参数说明和返回值等信息，具体可参考CONTRIBUTING.md中的示例。

2.3 提交Pull Request

完成代码开发后，按照以下步骤提交PR：

1. 创建特性分支：git checkout -b feat/your-feature-name
2. 提交代码：git commit -m "feat: add new feature description"
3. 推送到远程：git push origin feat/your-feature-name
4. 在GitHub上创建PR，填写相关信息并关联Issue

PR标题应遵循约定式提交规范，使用以下前缀：

• feat: 新功能
• fix: 错误修复
• docs: 文档更新
• style: 代码风格调整
• refactor: 代码重构
• test: 测试相关
• chore: 维护任务

3. 代码审查与质量检查

3.1 审查流程概述

PR提交后，需要经过代码审查流程：

1. 至少一名审阅者进行代码检查
2. 根据反馈进行修改
3. 通过所有检查后由维护者合并

审查重点包括功能正确性、代码质量、测试覆盖率和文档完整性等方面。

3.2 本地检查工具

在提交PR前，应在本地运行以下检查确保代码质量：

# 运行所有测试
pytest test

# 执行代码格式化和 lint 检查
pre-commit run --all-files

# 生成覆盖率报告
pytest --cov --cov-report=html

成功通过所有检查的PR状态示例

4. 文档贡献与测试

4.1 文档编写指南

OASIS使用Mintlify构建文档，贡献文档的步骤：

1. 安装Mintlify CLI：npm install -g mintlify
2. 进入文档目录：cd docs
3. 启动本地服务器：mintlify dev
4. 编辑文档并预览效果

所有文档都应放在docs目录下，遵循项目的文档规范。

4.2 测试编写要求

为确保代码质量，不同类型的贡献需要相应的测试支持：

• 错误修复：添加相关单元测试（位于test目录）
• 功能改进：更新受影响的示例脚本和单元测试
• 新功能：提供完整的单元测试和示例脚本（位于examples目录）

5. 常见问题与帮助资源

5.1 遇到困难怎么办

如果在开发过程中遇到问题，可以：

• 在Discord或微信群中提问（@doudou_wu或@张再斌）
• 在Issue中详细描述问题现象和复现步骤
• 参考项目examples目录中的示例代码

5.2 贡献被接受后的后续步骤

一旦你的PR被合并：

1. 相关Issue会自动关闭
2. 可以选择在发布说明中添加你的贡献
3. 项目维护者可能会在社交媒体上提及你的贡献（需提前告知账号信息）

OASIS模拟展示了信息在社交网络中的传播效果

总结

通过本文档，你已经了解了OASIS项目的完整贡献流程。无论是修复错误、改进功能还是添加新特性，你的每一个贡献都将帮助OASIS变得更好。记住，开源贡献是一个学习和成长的过程，不要害怕提问或犯错。加入我们，一起构建这个令人兴奋的智能体社交互动模拟平台！

【免费下载链接】oasis 🏝️ OASIS: Open Agent Social Interaction Simulations with One Million Agents. 项目地址: https://gitcode.com/gh_mirrors/oasis2/oasis