OpenWikihuggingface/transformers

Contributor Guide

Purpose and Scope

This page orients contributors who want to improve 🤗 Transformers without creating unnecessary review burden for maintainers. A contribution can be a code fix, an issue with a clear reproduction, a model implementation, a documentation improvement, an example, or a specialized integration such as a quantization backend. The contributor guide repeatedly emphasizes that all community contributions matter, including answering questions, helping other users, improving docs, and promoting the project when it enables useful work. It also frames contribution as a collaborative process: start from a well-scoped problem, explain the motivation, keep the change focused, and make the result easy to review.

Sources: docs/source/de/contributing.md, docs/source/ko/contributing.md, docs/source/zh/contributing.md

The English documentation entry at docs/source/en/contributing.md points readers to the repository-level contributing material, while the localized German, Korean, Romanian, and Chinese pages expose the same community expectations to a wider audience. Those localized pages are important because they preserve the first-party tone: contributors are welcome, code is not the only path, the code of conduct applies, and beginner-friendly issues are the recommended starting point when a contributor does not already have a specific fix in mind. For this OpenWiki page, treat those localized documents as the source of the general workflow and the quantization contribution page as the source for method-specific integration work.

Sources: docs/source/en/contributing.md, docs/source/de/contributing.md, docs/source/ko/contributing.md, docs/source/ro/contributing.md, docs/source/zh/contributing.md

Relevant Source Files

  • docs/source/en/contributing.md - English documentation entry for the contributor guide; in this snapshot it delegates to the repository contributing document.
  • docs/source/de/contributing.md - German contributor guide covering ways to contribute, issue reporting, beginner issue labels, and community expectations.
  • docs/source/ko/contributing.md - Korean contributor guide covering bug reports, feature requests, environment diagnostics, model proposals, documentation work, and pull request setup.
  • docs/source/ro/contributing.md - Romanian contributor guide excerpt that includes the current policy on code-agent-generated PRs and the preferred human review value: diagnosis, reproduction, and small diffs.
  • docs/source/zh/contributing.md - Chinese contributor guide covering the full path from issue reporting through fork, clone, branch, and pull request creation.
  • docs/source/en/quantization/contribute.md - Quantization-specific contributor guide for adding a new method through HfQuantizer, quantization config classes, integration files, and quantizer files.

Contribution Paths

The standard contribution paths are intentionally broad. If you found a bug in existing code and already understand the fix, the docs invite you to open a pull request. If you found a bug but do not yet know the fix, the expected contribution is a high-quality issue: search existing issues first, confirm the problem belongs to Transformers rather than local user code, and provide enough information for someone else to reproduce it quickly. The localized guides call out useful issue contents such as operating system, Python version, PyTorch or TensorFlow version, a short standalone reproduction, the complete traceback, screenshots, and transformers env output.

Sources: docs/source/ko/contributing.md, docs/source/zh/contributing.md

Feature requests follow a similar principle: make the maintainer’s next step obvious. The contributor docs ask for the motivation, a detailed description, a usage snippet, and related paper links when the request is research-driven. That structure matters in Transformers because new capabilities often affect many model families, backends, tasks, and documentation pages. A well-written request is not just a wish list item; it narrows the design space and gives maintainers enough context to judge whether the feature belongs in the library, in an example, in documentation, or in a companion project.

Sources: docs/source/de/contributing.md, docs/source/ko/contributing.md, docs/source/zh/contributing.md

For new contributors, the recommended discovery path is to start with the repository’s Good First Issue list and then move to Good Second Issue labels when ready for more complex work. The docs encourage contributors to comment on the issue they want to address and, where possible, link a pull request to the issue. That keeps progress visible and lets another contributor or maintainer pick up the work if the original author becomes unavailable. For larger work, especially new models or substantial features, open an issue first unless the change is already agreed upon or obviously small.

Sources: docs/source/de/contributing.md, docs/source/ko/contributing.md, docs/source/zh/contributing.md

Pull Request Workflow

A pull request should begin with coordination, not code. Search open issues and PRs to avoid duplicating someone else’s effort, ask for feedback when the design is unclear, then fork the repository, clone your fork, and add the upstream remote. The Chinese contributor guide includes the expected Git sequence: fork the Hugging Face Transformers repository, clone git@github.com:<your Github handle>/transformers.git, cd transformers, and add https://github.com/huggingface/transformers.git as upstream. It also states the Python requirement as Python 3.9 or newer for contributing in this repository snapshot.

Sources: docs/source/zh/contributing.md

git clone git@github.com:<your Github handle>/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git
git checkout -b my-focused-change

The most reviewable PRs are small, motivated, and easy to validate. The current contributor guidance, reflected in the Romanian page and official docs evidence, explicitly warns that the repository is under pressure from large numbers of code-agent-written PRs and issue comments. The maintainer request is not a blanket ban on using tools for drafting or diagnosis; it is a request that contributors do the human work an autonomous agent cannot do alone. That includes reproducing the problem, identifying the first bad commit when relevant, comparing similar model implementations, and removing unrelated files or exploratory scripts before opening the PR.

Sources: docs/source/ro/contributing.md

Use code agents cautiously and own the result. If a change appears fully agent-written, the docs warn it may be closed without review. A useful AI-assisted contribution still needs a clear problem statement, a minimal diff, repository-specific reasoning, and tests that demonstrate the behavior. Transformers contains many similar model implementations, so maintainers value PR descriptions that say, in effect, “this follows the same pattern as another model or subsystem,” with a link or explanation. That comparison helps reviewers understand compatibility with existing conventions instead of reverse-engineering the intent from a large generated diff.

Sources: docs/source/ro/contributing.md

Adding Models, Pipelines, and Processors

When proposing a new model, begin with context: a brief model description, a paper link, an implementation link if one exists, and model weight links if weights are available. The contributor guides invite authors to say whether they want to contribute the model themselves so maintainers can help route the work. In practice, adding a model is more than adding modeling code. It usually touches configuration, tokenizer or processor support, model outputs, documentation, tests, conversion scripts or checkpoints, and sometimes pipeline task support. A strong proposal makes those pieces visible early so reviewers can identify missing public API or compatibility requirements.

Sources: docs/source/ko/contributing.md, docs/source/zh/contributing.md

For pipelines, official guidance frames the task around subclassing Pipeline and deciding simple Python inputs and outputs before implementation. A new pipeline should keep inputs and outputs easy to use and preferably JSON-serializable, then implement _sanitize_parameters, preprocess, _forward, and postprocess. That design sequencing is important for contributors: first decide the user-facing contract, then map it to model inputs and outputs. Pipelines are public ergonomics, not just internal wrappers, so reviewers will care whether the API supports common input forms without forcing users to learn model-specific object types.

Sources: docs/source/en/contributing.md

Processors belong to the same contributor mindset because they sit at the boundary between raw user data and model tensors. A processor contribution should explain which modalities it combines, such as tokenizer plus image, audio, video, or multimodal preprocessing, and how it preserves compatibility with Auto classes and task pipelines. Even when the supplied source evidence for this page does not include the dedicated processor guide, the contributor docs’ broader expectations still apply: open an issue when the design is unclear, provide reproducible examples, document behavior, and keep the implementation consistent with neighboring models or processors.

Sources: docs/source/de/contributing.md, docs/source/ko/contributing.md, docs/source/zh/contributing.md

Quantization Contributions

Quantization has a more specialized contribution path. The quantization guide says Transformers already supports methods such as QLoRA, GPTQ, LLM.int8, and AWQ, and it directs contributors adding a new method toward HfQuantizer. The important distinction is that HfQuantizer is described as an internal helper for integrating a quantization method, not a generic wrapper applied blindly to every PyTorch module. A contributor should first verify that the method is suitable for Transformers: it should run with PyTorch modules, be available from a pip-installable package or installable source package, work on common hardware, and have stable kernels or primitives.

Sources: docs/source/en/quantization/contribute.md

The quantization guide gives a concrete implementation shape. A supported method should expose quantized layers as torch.nn.Module implementations, commonly replacing nn.Linear with a target class whose forward calls the quantized kernel. It should be serializable so quantized weights can be saved locally or pushed to the Hub. For approaches requiring calibration or pre-quantization, such as AWQ-style workflows, the guide says Transformers prefers to support inference and let the external library maintain the actual quantization procedure. That boundary keeps Transformers focused on loading, dispatching, serialization, and inference integration rather than owning every calibration algorithm.

Sources: docs/source/en/quantization/contribute.md

A new quantization method normally updates or creates three kinds of files: a quantization config class in src/transformers/utils/quantization_config.py, an integration file, and a quantizer file such as the Finegrained FP8 example referenced by the docs. The guide also calls out updating the public import structure in src/transformers/__init__.py. For contributors, the review expectation is therefore both API and runtime: define the configuration users pass at load time, implement the backend-specific replacement or dispatch logic, expose the symbols through the package, and prove that serialization and device behavior work for realistic models.

Sources: docs/source/en/quantization/contribute.md

Testing and Review Signals

Testing is part of the contribution, not a follow-up chore. The supplied official testing documentation describes a mixin-based model test architecture that can generate broad coverage from a small amount of model-specific test code. Common model-family bases include CausalLMModelTest, VLMModelTest, and ALMModelTest, with mixins for model behavior, generation, pipelines, training, and tensor parallelism depending on the class. Contributors working on models should choose the closest existing base class or build from the two-class tester pattern when the architecture does not match those families.

Sources: docs/source/en/contributing.md

Run focused tests before opening the PR and include the commands in your PR description when they are relevant. The official testing flow shows commands such as pytest tests/models/mymodel/test_modeling_mymodel.py -v, selecting a single test with ::MyModelTest::test_model, filtering integration tests with -k integration, and enabling slow tests with RUN_SLOW=1. The contributor docs’ issue-reporting advice reinforces the same principle from the other side: maintainers need concise reproductions and complete diagnostic information. A PR that includes both the failing case and the passing fix is much easier to review.

Sources: docs/source/ko/contributing.md, docs/source/zh/contributing.md

pytest tests/models/mymodel/test_modeling_mymodel.py -v
pytest tests/models/mymodel/test_modeling_mymodel.py::MyModelTest::test_model
pytest tests/models/mymodel/ -k integration -v
RUN_SLOW=1 pytest tests/models/mymodel/ -v

Practical Next Steps

If you are new, choose a Good First Issue, reproduce it locally, and leave a short comment explaining that you plan to work on it. If you are reporting a bug, search first, then attach transformers env output, a minimal reproduction, the full traceback, and any screenshots or context needed to understand the failure. If you are adding a model, pipeline, processor, or quantization method, start by writing down the public contract and comparing it with the closest existing subsystem. Before opening the PR, remove unrelated changes, run focused tests, and make the description explain why the change belongs in Transformers.

Sources: docs/source/de/contributing.md, docs/source/ko/contributing.md, docs/source/ro/contributing.md, docs/source/zh/contributing.md, docs/source/en/quantization/contribute.md

Ask a question...