Skip to content

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.

Python
5.2 KB
Raw Blame

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

  • 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:

  1. JiuwenSwarm version (jiuwenswarm --version)
  2. OS and Python version
  3. Reproduction steps
  4. Expected behavior vs actual behavior
  5. Relevant logs (~/.jiuwenswarm/logs/ and ~/.jiuwenswarm/agent/.logs)

Submitting Pull Requests

  1. Fork the repo: Fork openJiuwen/jiuwenswarm on GitCode

  2. Create a branch:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
  1. Develop and test: Run tests after making changes
uv run pytest tests/unit_tests/
  1. Commit your changes:
git add .
git commit -m "feat: add XXX feature"
  1. 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

  1. Automated checks: Tests run automatically when a PR is created
  2. Code review: At least two Committers must approve
  3. Revision feedback: Address review comments and push updates
  4. 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 develop as release/vX.Y.Z
  • Version numbers follow Semantic Versioning: MAJOR.MINOR.PATCH
  • After release, create Release Notes on GitCode Releases

Contact