General Contributing Workflow

AgentCompass uses a fork-and-pull-request workflow. This page explains how to prepare one focused change, implement and validate it against the owning contract, and submit a reviewable pull request. Detailed testing and documentation requirements live in their respective guides.

Prepare the Change

Before writing code, confirm the scope and governing contract:

1. Search existing issues and pull requests for overlapping work.
2. Read the architecture overview and locate the component that owns the behavior.
3. Inspect the current implementation, config schema, adjacent components, and public documentation.
4. When the change depends on an external project, establish the upstream contract from its official repository, API, paper, or provider documentation.
5. Open an issue or design discussion before a broad contract change or an integration with significant maintenance cost.

Keep each pull request focused on one clear problem. Do not combine unrelated refactors, dependency upgrades, formatting, or feature work.

Then follow GitHub’s contributing to a project workflow to fork, clone, and create a branch:

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
git switch --create feat/<short-topic> upstream/main

origin should point to your fork, and upstream should point to open-compass/AgentCompass. Name the branch after the change it contains, for example:

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

Implement and Validate

During implementation:

• Keep behavior in the component that owns it.
• Preserve explicit user settings before applying inferred defaults.
• Add public parameters through the corresponding 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 documentation in the same pull request when public behavior changes; follow the documentation contribution guide for the detailed rules.
• Never commit credentials, private endpoints, datasets, container layers, complete result directories, or large generated artifacts.

When changing a component, also meet the completion requirements in its integration guide: Benchmark, Harness, Environment, Recipe, or Analyzer.

Organize the work into atomic commits, using 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
chore	Maintenance, tooling, or dependency work	chore: update documentation tooling

Write concise, imperative subjects. Avoid vague messages such as update code or fix issue. If the implementation, Recipe, and documentation can be reviewed independently, commit them separately:

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

Start with the smallest check that directly exercises the modified contract, then expand according to risk to a representative real task and relevant failure paths. Before requesting review, complete the repository’s required full checks. Record exact redacted commands, relevant versions, important results, and the reasons and risks for any required checks you did not run.

Use the testing and validation guide to select checks, task evidence, and boundary cases. For changes to public pages, navigation, examples, or localization, also follow the documentation contribution guide.

Submit the Pull Request

Before opening or updating the pull request, rebase the branch onto the latest upstream/main:

git fetch upstream
git rebase upstream/main

Push a new branch with:

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

After rebasing a previously published personal feature branch, update that branch with:

git push --force-with-lease

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

The pull request description should explain:

• The problem, the scope of this change, and work intentionally left out.
• The owning component, important design decisions, and user-visible behavior and compatibility before and after the change.
• Exact redacted reproduction or validation commands, important results, and any necessary artifact evidence.
• Documentation updated with the implementation.

Before requesting review, complete the pull request checklist.

Handle Dependent Changes

When an integration depends on reusable infrastructure, submit the infrastructure and integration as separate pull requests so the infrastructure remains independently reviewable and reusable:

1. Create a foundational branch from upstream/main and submit the foundational pull request.
2. Create the integration branch on top of the foundational branch only for local combined testing and the later integration pull request.
3. After the foundational pull request merges, rebase the integration branch onto the updated upstream/main.
4. Inspect the commit range, rerun affected validation, and then update the personal integration branch with --force-with-lease.

Describe only each pull request’s own scope, and state the dependency and merge order. The foundational change must not depend on the Benchmark or Harness that first exercises it.