evotraders/CONTRIBUTING_en.md

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).

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

Note: If you want to contribute your own example, please also open an issue first to discuss your idea and avoid duplicate work.

Contributing Code

Setup

1. Fork and clone the repository
2. Install pre-commit:

   pip install pre-commit
   pre-commit install
   

3. Create a branch:

   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

   ## 🌳 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:

   pip install -r requirements.txt
   

5. Setup: Environment variables or configuration steps

6. Usage: How to run the example

   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:

pre-commit run --all-files

Submitting Your Contribution

1. Commit with clear messages:

   git commit -m "Add: new browser automation sample"
   

   Use prefixes: Add:, Fix:, Update:, Doc:

2. Push to your fork:

   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!