General Contributing Workflow

Fork AgentCompass, develop one focused change, validate it, and submit a reviewable pull request.

AgentCompass uses a fork-and-pull-request workflow. Keep each contribution focused, base it on the latest official main, and provide enough evidence for maintainers to review behavior, compatibility, and user impact.

Before Writing Code

1. Search existing issues and pull requests for overlapping work.
2. Read the architecture overview and locate the owning component.
3. Inspect the current implementation, config schema, adjacent components, and public documentation.
4. Establish an upstream contract from official repositories, APIs, papers, or provider documentation when applicable.
5. Open an issue or design discussion before a broad contract change or integration with significant maintenance cost.

Keep reusable infrastructure separate from the integration that consumes it. For example, provider-wide network control or resource limits should be reviewable independently from one benchmark.

Fork and Clone

Follow GitHub’s contributing to a project workflow:

git clone https://github.com/<your-user>/AgentCompass.git
cd AgentCompass

git remote add upstream https://github.com/open-compass/AgentCompass.git
git fetch upstream
git remote -v

origin should point to your fork. upstream should point to open-compass/AgentCompass.

Create a Focused Branch

Start from the latest upstream branch:

git fetch upstream
git switch --create feat/<short-topic> upstream/main

Use a branch name that describes one reviewable concern:

feat/add-example-benchmark
fix/daytona-image-precedence
docs/restructure-developer-guide

Do not combine unrelated refactors, dependency upgrades, formatting, and feature work in one pull request.

Develop Against the Owning Contract

During implementation:

• Keep behavior in the component that owns it.
• Preserve explicit user settings before applying inferred defaults.
• Add public parameters through the component config contract.
• Keep provider and model calls out of deterministic planning code.
• Preserve error categories and clean up resources on every exit path.
• Update user-facing documentation with the source change.
• Never commit credentials, private endpoints, datasets, container layers, or complete result directories.

Use the integration-specific completion requirements when changing a component:

• Benchmark Integration
• Harness Integration
• Environment Integration

Write Atomic Commits

Use the same change-type prefix for commit subjects and pull request titles:

Prefix	Use for	Example
feat	New user-facing behavior or component support	feat: add example benchmark
fix	Correctness, compatibility, or regression fixes	fix: preserve explicit task images
docs	Documentation-only changes	docs: add benchmark integration guide
style	Formatting with no behavior change	style: normalize code formatting
refactor	Internal restructuring with equivalent behavior	refactor: simplify result processing
test	Test or validation infrastructure	test: cover recipe precedence
chore	Maintenance, tooling, or dependency work	chore: update documentation tooling

Write concise imperative subjects. Avoid messages such as update code, fix issue, or a summary of several unrelated changes. Prefer an atomic history such as:

feat: add example benchmark runtime
feat: add example benchmark recipes
docs: document example benchmark evaluation

Validate the Change

Start with the smallest check that exercises the modified contract, then expand to representative end-to-end behavior. Record exact commands and important outcomes for the pull request.

For Python formatting and linting, use the repository’s current pre-commit configuration:

uvx pre-commit run --all-files --show-diff-on-failure

For documentation:

cd docs
mint broken-links
mint validate

Also preview documentation with mint dev when changing navigation, MDX components, tables, tabs, or command examples.

Keep Documentation With the Implementation

Update documentation in the same pull request when a change affects public flags, SDK interfaces, component ids, parameters, defaults, compatibility, installation, dependencies, result formats, or recommended commands.

• Put installation and first-run behavior in Get Started.
• Put configuration, operation, and troubleshooting in the User Guide.
• Put architecture, implementation contracts, extension rules, and validation standards in the Developer Guide.
• Keep English and Chinese pages at matching relative paths unless maintainers explicitly approve staged localization.
• Add or remove pages in docs/docs.json, use root-relative locale links, and validate generated commands.

Do not make users infer a new default or compatibility rule from source code.

Rebase and Push

Before opening or updating the pull request:

git fetch upstream
git rebase upstream/main

Push a new branch to your fork:

git push --set-upstream origin feat/<short-topic>

After rebasing a previously published feature branch, update only that branch:

git push --force-with-lease

Never force-push a shared branch without coordinating with its collaborators.

Open a Reviewable Pull Request

The pull request should explain:

• The problem and why it belongs in AgentCompass.
• The owning component and material design decisions.
• User-visible behavior and compatibility before and after the change.
• Exact redacted smoke or reproduction commands.
• Validation results and relevant score or artifact evidence.
• Documentation updated with the implementation.
• Work intentionally left outside the current scope.

Use compact tables for compatibility matrices and result comparisons. Link stable external artifacts rather than committing large outputs or complete trajectories.

Stack Foundational and Integration Changes

When one contribution depends on reusable infrastructure:

1. Create a foundational branch from upstream/main.
2. Create the integration branch on top of the foundational branch for local combined testing.
3. Submit the foundational pull request first.
4. After it merges, rebase the integration branch onto the updated upstream/main.
5. Inspect the range and rerun affected validation before pushing with --force-with-lease.

Each pull request summary should describe only its own concern. The foundational change must not depend on the benchmark or harness that first exercises it.