diff --git a/CONTRIBUTING_en.md b/CONTRIBUTING_en.md new file mode 100644 index 0000000..e488ffc --- /dev/null +++ b/CONTRIBUTING_en.md @@ -0,0 +1,155 @@ +# How to Contribute + +Thank you for your interest in AgentScope Samples! AgentScope Samples provides ready-to-use agent examples built on AgentScope and AgentScope Runtime. We welcome all types of contributions, from new sample agent applications to bug fixes and documentation improvements. + +## Community + +Connect with us through: + +- **GitHub Discussions**: Ask questions and share experiences (in **English**) +- **Discord**: Join our Discord channel for real-time discussions +- **DingTalk**: Chinese users can join our DingTalk group + +## Reporting Issues + +### Bugs + +Before reporting a bug, please test with the latest version and search existing issues. When submitting a bug report, include: + +- Clear description of the issue and reproduction steps +- Code/error messages +- Environment details (OS, Python version, AgentScope version) +- Affected examples + +### Security Issues + +Report security issues through [Alibaba Security Response Center (ASRC)](https://security.alibaba.com/). + +## Requesting New Features + +If you'd like a feature or new type of example that doesn't exist in AgentScope Samples, please open a feature request issue on GitHub describing: + +- The feature or example and its purpose +- How it should work +- What problem it solves or what use case it demonstrates + + + +## Contributing Code + +### Setup + +1. **Fork and clone** the repository +2. **Install pre-commit**: + ```bash + pip install pre-commit + pre-commit install + ``` +3. **Create a branch**: + ```bash + git checkout -b feature/your-sample-name + ``` + +### Creating New Examples + +#### Directory Structure + +Choose an appropriate category (`browser_use/`, `conversational_agents/`, `deep_research/`, `evaluation/`, `functionality/`, `games/`) and create your example directory. If a suitable category doesn't exist, you can propose a new one in your pull request. + +**Simple example:** +``` +your_sample_name/ +├── README.md +├── main.py +├── your_agent.py +└── requirements.txt +``` + +**Full-stack example** (use `_fullstack_runtime` suffix): +``` +your_sample_fullstack_runtime/ +├── README.md +├── backend/ +│ ├── requirements.txt +│ └── ... +└── frontend/ + ├── package.json + └── ... +``` + +#### README.md Requirements (Mandatory) + +Your README.md **must** include: + +1. **Title and Description**: What the example demonstrates + +2. **Project Structure** (mandatory): File tree with descriptions + ```markdown + ## 🌳 Project Structure + + \`\`\` + . + ├── README.md # Documentation + ├── main.py # Entry point + ├── agent.py # Agent implementation + └── requirements.txt # Dependencies + \`\`\` + ``` + +3. **Prerequisites**: Python version, API keys, etc. + +4. **Installation**: + ```bash + pip install -r requirements.txt + ``` + +5. **Setup**: Environment variables or configuration steps + +6. **Usage**: How to run the example + ```bash + python main.py + ``` + +#### Standalone Installation + +Each example must include a standalone `requirements.txt` file listing all necessary dependencies to ensure it can be installed and run independently without relying on other examples. + +#### Code Quality + +We enforce the following using pre-commit hooks: + +- **Black**: Code formatting (line length 79) +- **flake8** and **pylint**: Code linting +- **mypy**: Type checking + +When writing example code: +- Add clear comments and follow existing code style +- Add type hints to function signatures +- Keep code simple and focused on demonstrating specific features + +Ensure all checks pass: +```bash +pre-commit run --all-files +``` + +### Submitting Your Contribution + +1. **Commit** with clear messages: + ```bash + git commit -m "Add: new browser automation sample" + ``` + Use prefixes: `Add:`, `Fix:`, `Update:`, `Doc:` + +2. **Push** to your fork: + ```bash + git push origin feature/your-sample-name + ``` + +3. **Create a Pull Request** including: + - Clear description of what the example demonstrates + - References to related issues (e.g., "Closes #123") + +4. **Code Review**: Address feedback from maintainers + +Thank you for contributing to AgentScope Samples! + diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md new file mode 100644 index 0000000..99b6ab8 --- /dev/null +++ b/CONTRIBUTING_zh.md @@ -0,0 +1,154 @@ +# 如何贡献 + +感谢您对 AgentScope Samples 的关注！AgentScope Samples 提供基于 AgentScope 和 AgentScope Runtime 构建的即用型智能体示例。我们欢迎各种类型的贡献，从新的示例智能体应用到错误修复和文档改进。 + +## 社区 + +通过以下方式与我们联系： + +- **GitHub Discussions**：提问和分享经验（使用**英文**） +- **Discord**：加入我们的 Discord 频道进行实时讨论 +- **钉钉**：中国用户可以加入我们的钉钉群 + +## 报告问题 + +### Bug + +报告 bug 前，请先测试最新版本并搜索已有问题。提交 bug 报告时，请包括： + +- 清晰的问题描述和复现步骤 +- 代码/错误信息 +- 环境详情（操作系统、Python 版本、AgentScope 版本） +- 受影响的示例 + +### 安全问题 + +通过[阿里巴巴安全响应中心（ASRC）](https://security.alibaba.com/)报告安全问题。 + +## 请求新功能 + +如果您希望有一个在 AgentScope Samples 中不存在的功能或新类型的示例，请在 GitHub 上开一个功能请求 issue 来描述： + +- 该功能或示例及其目的 +- 它应该如何工作 +- 它解决了什么问题或演示了什么用例 + + + +## 贡献代码 + +### 设置 + +1. **Fork 并克隆**仓库 +2. **安装 pre-commit**： + ```bash + pip install pre-commit + pre-commit install + ``` +3. **创建分支**： + ```bash + git checkout -b feature/your-sample-name + ``` + +### 创建新示例 + +#### 目录结构 + +选择合适的类别（`browser_use/`、`conversational_agents/`、`deep_research/`、`evaluation/`、`functionality/`、`games/`）并创建示例目录。如果不存在合适的类别，您可以在 pull request 中提议一个新类别。 + +**简单示例：** +``` +your_sample_name/ +├── README.md +├── main.py +├── your_agent.py +└── requirements.txt +``` + +**全栈示例**（使用 `_fullstack_runtime` 后缀）： +``` +your_sample_fullstack_runtime/ +├── README.md +├── backend/ +│ ├── requirements.txt +│ └── ... +└── frontend/ + ├── package.json + └── ... +``` + +#### README.md 要求（强制） + +您的 README.md **必须**包含： + +1. **标题和描述**：示例演示的内容 + +2. **项目结构**（强制）：带说明的文件树 + ```markdown + ## 🌳 项目结构 + + \`\`\` + . + ├── README.md # 文档 + ├── main.py # 入口点 + ├── agent.py # 智能体实现 + └── requirements.txt # 依赖项 + \`\`\` + ``` + +3. **前置要求**：Python 版本、API 密钥等 + +4. **安装**： + ```bash + pip install -r requirements.txt + ``` + +5. **设置**：环境变量或配置步骤 + +6. **使用方法**：如何运行示例 + ```bash + python main.py + ``` + +#### 独立安装 + +每个示例需包含独立的 `requirements.txt` 文件，列出所有必需的依赖项，以确保可独立安装和运行，不依赖其他示例。 + +#### 代码质量 + +我们使用 pre-commit hooks 强制执行： + +- **Black**：代码格式化（行长度 79） +- **flake8** 和 **pylint**：代码检查 +- **mypy**：类型检查 + +编写示例代码时： +- 添加清晰的注释，遵循现有代码风格 +- 为函数签名添加类型提示 +- 保持代码简单，专注于演示特定功能 + +确保通过所有检查： +```bash +pre-commit run --all-files +``` + +### 提交您的贡献 + +1. **提交**时使用清晰的消息： + ```bash + git commit -m "Add: new browser automation sample" + ``` + 使用前缀：`Add:`、`Fix:`、`Update:`、`Doc:` + +2. **推送**到您的 fork： + ```bash + git push origin feature/your-sample-name + ``` + +3. **创建 Pull Request**，包含： + - 示例演示内容的清晰描述 + - 相关问题的引用（例如 "Closes #123"） + +4. **代码审查**：处理维护者的反馈 + +感谢您为 AgentScope Samples 做出贡献！ \ No newline at end of file