AGENTS.md · modelscope/ms-swift

Sections

1. 1. Contribution Policy (Mandatory)
2. 2. Development Workflow
3. 3. Policy Maintenance
4. Acknowledgements

First lines (shown under the repo's Apache-2.0 license)

# Agent Instructions for ms-swift

> These instructions apply to **all** AI-assisted contributions to `modelscope/ms-swift`.
> Breaching these guidelines may result in your PR being closed.
> Read [`CONTRIBUTING.md`](CONTRIBUTING.md) (Chinese: [`CONTRIBUTING_CN.md`](CONTRIBUTING_CN.md)) first.

## 1. Contribution Policy (Mandatory)

### Human-submitted PRs

- Pure code-agent PRs are **not allowed**. A human submitter must understand and defend the change end-to-end.
- The pull request must be created and submitted by **a human** — never by an agent or an automated tool. The submission step always requires human involvement.
- The submitting human must review every changed line and run the relevant tests before submitting.

### Issue first, then PR

- Link the related issue in the PR description if there is one (e.g. `Fixes #123` for bug fixes, `Refs #123` for features/RFCs).
- If this is a first-time contribution to ms-swift, open an issue first (using the issue templates). PRs from first-time contributors that do not link an issue may be closed directly.

### Duplicate-work checks

Before proposing a PR, check whether an open PR already addresses the same fix:

```bash
gh issue view <issue-number> --repo modelscope/ms-swift --comments
gh pr list --repo modelscope/ms-swift --state open --search "<issue-number> in:body"
gh pr list --repo modelscope/ms-swift --state open --search "<short area keywords>"
```

- If an open PR already addresses the issue, do not open another one.
- If your approach is materially different, explain the difference in the issue first.

### No low-value busywork PRs

- Do not open one-off PRs for tiny edits (single typo, isolated style change, "theoretical bug" without a real usage path). Bundle mechanical cleanups into a systematic change, or open an issue to discuss first.

### Accountability

- PR descriptions for AI-assisted work **must** include:
  - The repository's PR template, filled in ([`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md): PR type, linked issue, checklist).
  - Test commands run and results; reproduction or experiment results when behavior changes (see `## Experiment results` in the template).
  - A clear statement that AI assistance was used.
- If you cannot explain how the change works and why it is correct, do not submit it — maintainers may ask.

### Fail-closed behavior

- If the work is duplicate or trivial busywork, **do not proceed**. Return a short explanation of what is missing instead of opening a PR.

## 2. Development Workflow

- **Environment**: develop against the repository checkout, not the released package — from the repo root run `pip install -e .` (or `uv pip install -e . --torch-backend=auto`), then install the test and lint dependencies: `pip install -r requirements/tests.txt`.
- **Lint (required)**: `pre-commit run --all-files` — fix any reported errors until all checks pass (the CI lint job runs the same command).
- **Docs**: when user-facing behavior or APIs change, update both docs trees (English `docs/source_en/`, Chinese `docs/source/`) and keep paired top-level files in sync (`README.md` / `README_CN.md`).
- **Commit attribution**: when an AI tool contributed non-trivially, add attribution trailers such as:

  ```text
  Co-authored-by: GitHub Copilot
  Co-authored-by: Claude
  ```

## 3. Policy Maintenance

- **Editing these instructions**: if a requested task conflicts with these rules, stop and explain the conflict — do not edit this file, `CONTRIBUTING.md` / `CONTRIBUTING_CN.md`, or the PR template to work around them. Changes to these files must go through normal human PR review.

## Acknowledgements

Adapted from the [vLLM project](https://github.com/vllm-project/vllm)'s [`AGENTS.md`](https://github.com/vllm-project/vllm/blob/main/AGENTS.md).