Skip to content

Commit a6a149a

Browse files
fang-techfang-tech
authored
docs(contributing): add contributing document (#126)
relate #107
1 parent 0d4cdc7 commit a6a149a

4 files changed

Lines changed: 662 additions & 3 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# Contributing to AgentScope
2+
3+
## Welcome! 🎉
4+
5+
Thank you for your interest in contributing to AgentScope! As an open-source project, we warmly welcome and encourage
6+
contributions from the community. Whether you're fixing bugs, adding new features, improving documentation, or sharing
7+
ideas, your contributions help make AgentScope better for everyone.
8+
9+
## How to Contribute
10+
11+
To ensure smooth collaboration and maintain the quality of the project, please follow these guidelines when contributing:
12+
13+
### 1. Check Existing Plans and Issues
14+
15+
Before starting your contribution, please review our development roadmap:
16+
17+
- **Check the [Issue](https://github.com/agentscope-ai/agentscope-java/issues) page**
18+
- **If a related issue exists** and is marked as unassigned or open:
19+
- Please comment on the issue to express your interest in working on it
20+
- This helps avoid duplicate efforts and allows us to coordinate development
21+
22+
- **If no related issue exists**:
23+
- Please create a new issue describing your proposed changes or feature
24+
- Our team will respond promptly to provide feedback and guidance
25+
- This helps us maintain the project roadmap and coordinate community efforts
26+
27+
### 2. Commit Message Format
28+
29+
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This leads to more readable
30+
commit history and enables automatic changelog generation.
31+
32+
**Format:**
33+
```
34+
<type>(<scope>): <subject>
35+
```
36+
37+
**Types:**
38+
- `feat:` A new feature
39+
- `fix:` A bug fix
40+
- `docs:` Documentation only changes
41+
- `style:` Changes that do not affect the meaning of the code (white-space, formatting, etc)
42+
- `refactor:` A code change that neither fixes a bug nor adds a feature
43+
- `perf:` A code change that improves performance
44+
- `ci:` Adding missing tests or correcting existing tests
45+
- `chore:` Changes to the build process or auxiliary tools and libraries
46+
47+
**Examples:**
48+
```bash
49+
feat(models): add support for Claude-3 model
50+
fix(agent): resolve memory leak in ReActAgent
51+
docs(readme): update installation instructions
52+
refactor(formatter): simplify message formatting logic
53+
ci(models): add unit tests for OpenAI integration
54+
```
55+
56+
### 3. Code Development Guidelines
57+
58+
#### a. Code Formatting
59+
60+
Before submitting code, you must ensure code is properly formatted using Spotless:
61+
62+
**Check code format:**
63+
```bash
64+
mvn spotless:check
65+
```
66+
67+
**Auto-fix format issues:**
68+
```bash
69+
mvn spotless:apply
70+
```
71+
72+
> **Tip**: Configure your IDE (IntelliJ IDEA / Eclipse) to format code on save using the project's code style.
73+
74+
#### b. Unit Tests
75+
76+
- All new features must include appropriate unit tests
77+
- Ensure existing tests pass before submitting your PR
78+
- Run tests using:
79+
```bash
80+
# Run all tests
81+
mvn test
82+
83+
# Run a specific test class
84+
mvn test -Dtest=YourTestClassName
85+
86+
# Run tests with coverage report
87+
mvn verify
88+
```
89+
90+
#### c. Documentation
91+
92+
- Update relevant documentation for new features
93+
- Include code examples where appropriate
94+
- Update the README.md if your changes affect user-facing functionality
95+
96+
97+
## Types of Contributions
98+
99+
### Adding New Chat Models
100+
101+
AgentScope currently supports the following API providers at the chat model level: **OpenAI**, **DashScope**,
102+
**Gemini**, **Anthropic**, and **Ollama**. These APIs are compatible with various service providers including vLLM,
103+
DeepSeek, SGLang, and others.
104+
105+
**⚠️ Important Notice:**
106+
107+
Adding a new chat model is not merely a model-level task. It involves multiple components including:
108+
- Message formatters
109+
- Token counters
110+
- Tools API integration
111+
112+
This is a substantial amount of work. To better focus our efforts on agent capability development and maintenance,
113+
**the official development team currently does not plan to add support for new chat model APIs**. However, when there
114+
is a strong need from the developer community, we will do our best to accommodate these requirements.
115+
116+
**If you wish to contribute a new chat model**, here are the components needed to be compatible with the
117+
existing `ReActAgent` in the repository:
118+
119+
#### Required Components:
120+
121+
1. **Chat Model Class** (under `io.agentscope.model`):
122+
```java
123+
package io.agentscope.model;
124+
125+
public class YourChatModel extends ChatModelBase {
126+
/**
127+
* The functionalities that you need to consider include:
128+
* - Tools API integration
129+
* - Both streaming and non-streaming modes (compatible with tools API)
130+
* - tool_choice argument
131+
* - reasoning models
132+
*/
133+
}
134+
```
135+
136+
2. **Formatter Class** (under `io.agentscope.formatter`):
137+
```java
138+
package io.agentscope.formatter;
139+
140+
public class YourModelFormatter extends FormatterBase {
141+
/**
142+
* Convert Msg objects into the format required by your API provider.
143+
* If your API doesn't support multi-agent scenarios (e.g. doesn't support
144+
* the name field in messages), you need to implement two separate formatter
145+
* classes for chatbot and multi-agent scenarios.
146+
*/
147+
}
148+
```
149+
150+
3. **Token Counter** (under `io.agentscope.token`, recommended):
151+
```java
152+
package io.agentscope.token;
153+
154+
public class YourTokenCounter extends TokenCounterBase {
155+
/**
156+
* Implement token counting logic for your model.
157+
* This is recommended but not strictly required.
158+
*/
159+
}
160+
```
161+
162+
### Adding New Agents
163+
164+
To achieve true modularity, the `io.agentscope.agent` package currently aims to maintain only the **`ReActAgent`** class
165+
as the core implementation. We ensure all functionalities in this class are **modular, detachable, and composable**.
166+
167+
In AgentScope, we follow an examples-first development workflow: prototype new implementations in the `agentscope-examples/`
168+
module, then abstract and modularize the functionality, and finally integrate it into the core library.
169+
170+
For specialized or domain-specific agents, we recommend contributing them to the **`agentscope-examples`** module:
171+
172+
```
173+
agentscope-examples/
174+
└── your-example/
175+
├── pom.xml
176+
├── src/main/java/
177+
│ └── io/agentscope/examples/
178+
│ └── YourAgent.java
179+
└── README.md # Explain the agent's purpose and usage
180+
```
181+
182+
### Adding New Examples
183+
184+
We highly encourage contributions of new examples that showcase the capabilities of AgentScope.
185+
Please add them to the `agentscope-examples/` module with a clear README explaining the purpose and usage of the example.
186+
187+
Our examples are organized as Maven submodules:
188+
189+
- `agentscope-examples/quickstart/` for getting started examples
190+
- `agentscope-examples/advanced/` for advanced usage examples
191+
- `agentscope-examples/werewolf/` for game-related examples
192+
193+
An example structure could be:
194+
195+
```
196+
agentscope-examples/
197+
└── {example_name}/
198+
├── pom.xml
199+
├── src/
200+
│ └── main/
201+
│ ├── java/
202+
│ │ └── io/agentscope/examples/{example_name}/
203+
│ │ └── Main.java
204+
│ └── resources/
205+
│ └── logback.xml
206+
└── README.md # Explain the example's purpose and usage
207+
```
208+
209+
210+
## Do's and Don'ts
211+
212+
### ✅ DO:
213+
214+
- **Start small**: Begin with small, manageable contributions
215+
- **Communicate early**: Discuss major changes before implementing them
216+
- **Write tests**: Ensure your code is well-tested
217+
- **Document your code**: Help others understand your contributions
218+
- **Follow commit conventions**: Use conventional commit messages
219+
- **Be respectful**: Follow our Code of Conduct
220+
- **Ask questions**: If you're unsure about something, just ask!
221+
222+
### ❌ DON'T:
223+
224+
- **Don't surprise us with big pull requests**: Large, unexpected PRs are difficult to review and may not align with project goals. Always open an issue first to discuss major changes
225+
- **Don't ignore CI failures**: Fix any issues flagged by continuous integration
226+
- **Don't mix concerns**: Keep PRs focused on a single feature or fix
227+
- **Don't forget to update tests**: Changes in functionality should be reflected in tests
228+
- **Don't break existing APIs**: Maintain backward compatibility when possible, or clearly document breaking changes
229+
- **Don't add unnecessary dependencies**: Keep the core library lightweight
230+
231+
## Getting Help
232+
233+
If you need assistance or have questions:
234+
235+
- 💬 Open a [Discussion](https://github.com/agentscope-ai/agentscope-java/discussions)
236+
- 🐛 Report bugs via [Issues](https://github.com/agentscope-ai/agentscope-java/issues)
237+
- 📧 Contact the maintainers at DingTalk or Discord (links in the README.md)
238+
239+
240+
---
241+
242+
Thank you for contributing to AgentScope! Your efforts help build a better tool for the entire community. 🚀

0 commit comments

Comments
 (0)