> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/en/developer_guide/architecture) 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](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)
workflow:

```bash theme={"system"}
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:

```bash theme={"system"}
git fetch upstream
git switch --create feat/<short-topic> upstream/main
```

Use a branch name that describes one reviewable concern:

```text theme={"system"}
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](/en/developer_guide/benchmark_integration)
* [Harness Integration](/en/developer_guide/harness_integration)
* [Environment Integration](/en/developer_guide/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:

```text theme={"system"}
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:

```bash theme={"system"}
uvx pre-commit run --all-files --show-diff-on-failure
```

For documentation:

```bash theme={"system"}
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:

```bash theme={"system"}
git fetch upstream
git rebase upstream/main
```

Push a new branch to your fork:

```bash theme={"system"}
git push --set-upstream origin feat/<short-topic>
```

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

```bash theme={"system"}
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.