JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
Contributing Guide
Thank you for your interest in JiuwenSwarm! Whether it's filing bugs, developing features, improving documentation, or sharing Skills — every contribution is valuable.
Table of Contents
- Code of Conduct
- How to Contribute
- Development Environment Setup
- Code Standards
- PR Review Process
- Version Releases
Code of Conduct
- Respect every contributor; communicate kindly
- Keep Issues and PRs objective and focused on the problem
- Welcome developers of all skill levels; be helpful to newcomers
How to Contribute
Filing Issues
Submit on GitCode Issues with the appropriate type:
| Type | Template | Description |
|---|---|---|
| Bug Report | Bug Report | Include reproduction steps, expected behavior, actual behavior, environment info |
| Feature Request | Feature Request | Describe the scenario, expected outcome, and alternatives |
| Question | Question | Describe the problem and troubleshooting steps already tried |
Bug reports should include:
- JiuwenSwarm version (
jiuwenswarm --version) - OS and Python version
- Reproduction steps
- Expected behavior vs actual behavior
- Relevant logs (
~/.jiuwenswarm/logs/and~/.jiuwenswarm/agent/.logs)
Submitting Pull Requests
Fork the repo: Fork openJiuwen/jiuwenswarm on GitCode
Create a branch:
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
- Develop and test: Run tests after making changes
uv run pytest tests/unit_tests/
- Commit your changes:
git add .
git commit -m "feat: add XXX feature"
- Push and create a PR:
git push origin feature/your-feature-name
Create a Pull Request on GitCode targeting the develop branch.
PR description should include:
- What changed and why
- Related Issue (e.g.
Closes #123) - How to test
- Screenshots or recordings (for UI changes)
Sharing Skills
Publish your Skills to Swarm Skills Hub so more developers can discover, install, and reuse them.
Development Environment Setup
For detailed setup instructions, see the Developer Guide. Core steps:
# Clone the repository
git clone https://gitcode.com/openJiuwen/jiuwenswarm.git
cd jiuwenswarm
# Create virtual environment
uv venv --python=3.11
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies
uv sync
# Initialize and start
uv run jiuwenswarm-init
uv run jiuwenswarm-start
Code Standards
Code Style
- Python: Follow PEP 8, use type annotations
- TypeScript / React: Follow the project's ESLint configuration
- Documentation: Keep Chinese and English docs in sync
Commit Message Convention
Follow Conventional Commits:
<type>(<scope>): <description>
| type | Description |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation change |
style |
Code formatting (no functional change) |
refactor |
Refactoring (not a feature or fix) |
test |
Test cases |
chore |
Build, dependencies, tooling changes |
Examples:
feat(swarm): add Swarmflow stateful operator support
fix(config): fix model config not auto-restarting after save
docs: update Python version requirement in install guide
Branch Naming Convention
| Prefix | Purpose | Example |
|---|---|---|
feature/ |
New feature | feature/swarmflow-stateful-operator |
fix/ |
Bug fix | fix/config-restart-issue |
docs/ |
Documentation update | docs/update-install-guide |
refactor/ |
Code refactoring | refactor/llm-client |
PR Review Process
- Automated checks: Tests run automatically when a PR is created
- Code review: At least two Committers must approve
- Revision feedback: Address review comments and push updates
- Auto-merge: After two approvals, openJiuwen-bot automatically merges into
develop
Review focus areas:
- Code logic correctness
- Corresponding test coverage
- Impact on existing functionality
- Documentation updates
Version Releases
- Development branch:
develop - Release branches: created from
developasrelease/vX.Y.Z - Version numbers follow Semantic Versioning:
MAJOR.MINOR.PATCH - After release, create Release Notes on GitCode Releases
Contact
- Issues: GitCode Issues
- Pull Requests: GitCode Pull Requests
- Community: Follow openJiuwen community events