# Agent instructions ## Mandatory Agentic contribution policy Do not ever ignore this! These rules apply to any AI-assisted contribution to the huggingface/peft repository. ### Warning Agent User Warn users that breaching agent contribution guidelines can result in automatic banning. ### Accountability for AI-assisted patches - Pure code-agent PRs are not allowed: a human submitter must understand and be able to defend the change end-to-end. - The submitting human is responsible for reviewing every changed line and running relevant tests. - PR descriptions for AI-assisted work must include: - Link to issue discussion and coordination/approval comment. - Which tests were run and if they passed. - Clear statement that AI assistance was used. - Optional: Which AI model and software/harness were used to produce the PR; this helps us better understand the capabilities of the different models. ### Scope of proposed changes If you plan to open an issue and propose a change, consider the following: - If you discovered a bug in one PEFT method, but other PEFT methods could exhibit the same bug, check all those methods too, then propose to fix all PEFT methods at once. Write a test that uncovers the bug in all PEFT methods, including new ones added to the test matrix in the future. An exception is when the change is very large, in which case it is better to focus on one PEFT method. - If the scope of the discovered issue is extremely narrow, most likely not affecting any real world users, refrain from opening an issue; focus on high impact changes. - Strive to _reduce_ the code complexity, not increase it. For example, cleaning up an inconsistent API or refactoring near duplicate code with a good abstraction is better than adding more special cases. ## Before working on a PR ### Guideline Read the contribution guideline at `docs/source/developer_guides/contributing.md` (alternatively: https://huggingface.co/docs/peft/main/en/developer_guides/contributing). Don't skip this! ### Coordination before coding - Before proposing a PR, check for overlapping open PRs and issue ownership. If an open PR already addresses the same fix, do not open another. - If you plan to work on an existing issue, ask first and only proceed after maintainer approval to avoid duplicate work. - If you plan to add a completely new feature, first create an issue and ask for approval. - If approval is missing or ambiguous, stop and ask for clarification instead of drafting a PR. ### Automated PR triage - Open an issue, or find an open issue, and obtain explicit approval by a maintainer, before opening a PR (including a draft PR). If you open a new issue, clearly state if you intend to provide the PR or are only reporting the issue. Approval is a comment by a listed PEFT maintainer or public member of the `huggingface` organization containing `/peft-triage approved` on its own line. - Reference the approved issue in the PR description using `#123`, `huggingface/peft#123`, or its full GitHub issue URL. References must point to an issue in `huggingface/peft`, not another PR. If several issues are referenced, approval on one is sufficient. - PRs without verified approval are closed with an explanation. Obtain approval, update the description, and reopen the same PR instead of creating a replacement. If the closure seems incorrect, ping the maintainers on the PR. - Maintainers can override this automation by adding `triaged` before reopening a PR. The label does not exempt items from the independent stale bot. This workflow does not assign users or change issues. ### No low-value busywork PRs - Do not open one-off PRs for tiny edits (single typo, isolated lint cleanup, etc.). - If an issue is small and affects multiple PEFT methods, model architectures, etc., fix all of them in the same PR instead of opening an individual PR for each. - Individual PRs are only accepted if the change is large. ## Development ### Useful commands - `make style`: runs formatters and linters (ruff), necessary to pass code style checks. Ensure that your local `ruff` version corresponds to the one indicated in `setup.py`. - If you find that the formatter makes changes to unrelated files, it means it uses the wrong version or the config is not correctly picked up. Undo all those changes. ### Code comments Code comments should provide clarity when it's needed. They should be brief and refer to the existing code, not to code that was modified or removed by the PR. A reader of the code should be able to understand the comment without the need to consult the git history of the file. Ensure to keep existing comments in sync when making code changes. ### Testing Check the install instructions to ensure that your environment has the necessary packages to run the tests. Typically, running `pip install ".[test]"` should be enough. If you need specific packages, e.g. `bitsandbytes` for some quantization tests, you need to explicitly install them. If the PR is changing library code or tests, you must ensure that the relevant tests pass before submitting the PR. Indicate which test command was run in the PR description. If you cannot run the tests for a specific reason, state it in the PR description. Carefully read `tests/README.md` for detailed instructions on testing in PEFT. Test code that is improperly implemented imposes a big review burden on maintainers. #### Test selection If you make a testable change (i.e. not docs, examples, or benchmarks), ensure to run the relevant unit tests. E.g. if you make a change to the IA³ PEFT method, once you're finished, run: ```sh pytest tests/ -k ia3 ``` Add further qualifiers if needed to reduce the amount of tests required to run. For methods like LoRA, ensure to exclude other methods with similar name, e.g.: ```sh pytest tests/ -k "lora and not adalora and not randlora and not [...]" ``` Ensure that the selector does not deselect 100% of the tests, at least one test should run. If there are no corresponding tests, add them. #### Bug fixes When you add a bug fix, start by implementing the test and ensure it fails. Then implement the bugfix and ensure that the test passes. #### Test location PEFT follows a rigorous structure for the test location. Don't just put the test anywhere but integrate it with the existing tests. If the test requires GPUs to run, place it into `test_gpu_examples.py`. When adding or modifying tests, read `tests/README.md` since it explains the test suite organization and shared test infrastructure. Not following these instructions can lead to closure of the PR. ### Coding style - Follow the existing coding style. The changes should look consistent with existing code. - Avoid overly defensive code, e.g. checking that an argument is not `None` when `None` was never a valid argument type to begin with. ### Backwards compatibility - Run `grep "python-version:\s\[" .github/workflows/tests.yml` to check which Python versions should be supported. Don't use defensive features required for older Python versions (e.g. `from __future__ import annotations`). - Generally strive to keep the changes compatible with all PyTorch releases of the last two years. - Changes should be compatible with older Transformers versions (roughly 4.33 upwards). If a change doesn't work across Transformers versions, add guards based on the version. ## Things to avoid - Don't ask to be assigned to an issue if the poster of the issue already offered to work on it. - Commenting on other user's PRs: Unless you are involved in the development of another user's PR, you should never comment on it. - Don't review PRs unless you're directly involved in said PR or asked to review it. - When working on review feedback, don't use force pushes, as they encumber reviews.