# Contribua para o 🤗 Transformers

## Regras de contribuição

Existem duas formas de abrir um PR: corrigir uma issue que está aberta para contribuições, ou abrir um PR independente que contenha suas próprias evidências. Novos modelos também podem ser adicionados com um PR independente, veja [Adicionando um novo modelo](#adding-a-new-model). A equipe da Hugging Face, os mantenedores e alguns contribuidores de longa data estão isentos dessas regras.

**Corrigindo um problema.** Vincule o problema com uma palavra-chave de fechamento, como `Fixes #123`, na descrição do PR. Você pode trabalhar em:

- uma issue que você abriu, assim que um mantenedor a rotular como `triaged`
- uma issue com a etiqueta [`contributions-welcome`](https://github.com/huggingface/transformers/labels/contributions-welcome)
- uma issue com a etiqueta [`New model`](https://github.com/huggingface/transformers/labels/New%20model), consulte [Adicionando um novo modelo](#adding-a-new-model)

Problemas de outras pessoas não estão abertos para PRs, a menos que um mantenedor tenha dito o contrário. PRs que vinculam um problema no qual você não pode trabalhar serão fechados.

Você não precisa pedir permissão antes de trabalhar em uma issue que atenda aos critérios, e não atribuímos issues a pessoas. Comentários como "posso trabalhar nisso?" ou "por favor, atribua isso a mim" apenas adicionam ruído, então pule-os e abra seu PR. O primeiro PR para uma issue tem prioridade.

Antes de trabalhar em uma issue de `contributions-welcome` ou `New model`, verifique se alguém já abriu um PR para ela. Se sim, não abra outro. Se você notar erros, deixe sugestões no PR existente. Abra um PR concorrente apenas se o existente for fundamentalmente defeituoso ou obsoleto: seu autor não respondeu a comentários de revisão ou não enviou alterações há duas semanas. Um PR que está aguardando revisão de um mantenedor não é obsoleto. De qualquer forma, explique o motivo na issue antes de abrir o seu.

**PRs independentes.** Se ninguém ainda reportou o problema, você pode abrir um PR sem um issue. PRs independentes são para mudanças curtas com impacto real, como a correção de um bug, uma melhoria de desempenho ou a correção de um exemplo quebrado na documentação. A descrição do PR precisa das mesmas evidências que um issue:

- para um bug, um script curto que falha no `main` e passa com sua correção, usando um checkpoint publicado, uma configuração padrão ou um fluxo de trabalho documentado
- para uma melhoria de desempenho, números antes e depois em uma carga de trabalho realista, como um checkpoint publicado ou uma configuração padrão, e o hardware em que você executou. Um microbenchmark mais rápido de uma função que não está em um caminho crítico não conta.

Se já existir uma issue para o problema, seu PR passa por essa issue, independentemente de você vinculá-la ou não. PRs isolados que corrigem uma issue existente, ou que vêm sem evidências, serão fechados. Esses requisitos não se aplicam a novos modelos.

**Alterações que exigem uma issue antes.** Limpezas mecânicas que não afetam a correção ou o desempenho, e correções em massa de erros de digitação ou redação na documentação, exigem uma issue antes de um PR. Proponha a alteração, como você a faria e quantos arquivos ela afeta. Uma única correção de erro de digitação é pequena demais para um PR em qualquer um dos caminhos.

**Revisando PRs de outras pessoas.** Revisões da comunidade são bem-vindas quando nos informam algo novo, mas os mantenedores leem todos os comentários em um PR e já executamos nossas próprias ferramentas de revisão. Antes de comentar em um PR que você não abriu, certifique-se de ter algo específico a dizer:

- Se você encontrou um problema ou tem uma mudança concreta para propor, deixe um comentário inline nas linhas relevantes, idealmente como uma sugestão do GitHub que o autor pode aplicar diretamente. Um reprodutor ajuda se você estiver relatando um bug.
- Se você reportou o problema que o PR corrige, uma breve nota indicando se ele resolve o seu caso é muito útil.
- Por favor, não publique resumos gerais ou relatórios do tipo "testei e funciona". Aprovações de pessoas que não são mantenedoras não afetam se um PR será mesclado, e um comentário longo que apenas repete o conteúdo do PR consome nosso tempo sem alterar o resultado.

A forma como você escreve seu código fica a seu critério, mas você é responsável por tudo o que submete, e podemos bloquear contas que abrirem repetidamente issues ou PRs de baixa qualidade. Por favor, respeite também nosso [código de conduta](https://github.com/huggingface/transformers/blob/main/CODE_OF_CONDUCT.md).

 O que procuramos em problemas e PRs

- Diagnóstico claro de bugs. Soluções rápidas frequentemente causam inchaço no código ou incompatibilidades com outros modelos. Dedicar tempo para rastrear a causa exata de um problema, e em particular
localizar o primeiro commit em que o problema apareceu (por exemplo, com [git bisect](https://git-scm.com/docs/git-bisect)) é valioso.
- Minimize o diff. Verifique seu PR para eliminar qualquer alteração desnecessária. Certifique-se de que você não commitou nenhum script de teste
ou arquivos não relacionados. Adicione comentários apenas se forem realmente necessários. Se o seu PR puder ser uma correção de 1 linha, faça-o uma correção de 1 linha. Isso torna o PR muito mais fácil de revisar e melhora as chances de que ele seja aceito.
- Tome o tempo necessário para reproduzir o problema. Muito frequentemente, quando um usuário relata um problema, a causa real é
problemas de ambiente em sua máquina, ou eles diagnosticam incorretamente o problema e sugerem uma solução inválida. Confiar demais no relatório leva a soluções ruins, às vezes para problemas que nem existem! Escrever um script simples de reprodução e executá-lo para ter certeza de que você vê o problema é valioso.
- Compare com outros modelos. O repositório do Transformers é muito grande e muitos modelos fazem coisas semelhantes. Quando
Ao corrigir um bug, é valioso verificar se o bug existe em outros modelos. Se a sua PR disser "corrigido usando a mesma abordagem de (outro modelo)", com um link para o código relevante, isso é muito útil para os mantenedores, pois nos informa que a correção provavelmente está correta e é compatível com o restante da base de código.
- Evite PRs de "trabalho inútil". Não temos tempo para pequenas mudanças de estilo ou correções de erros de digitação em comentários, e não aceitamos
correções para "bugs teóricos" encontrados pela análise de código que raramente, ou nunca, causam problemas na prática, a menos que possam ser explorados por um atacante.
- Verifique os testes localmente e no CI. Antes de abrir um PR, execute `make fix-repo` e use `utils/tests_fetcher.py` para
veja uma lista de testes que cobrem os arquivos que você alterou no branch do seu PR. Execute esses testes localmente e certifique-se de que eles passam antes de abrir um PR. Após abrir o seu PR, verifique se o CI está verde e corrija quaisquer problemas antes de solicitar a revisão a alguém! Isso reduz muito o spam de notificações, o que mantém os mantenedores sãos.

## Configuração

1. Faça um fork do [Transformers](https://github.com/huggingface/transformers) com o botão **Fork** no GitHub para obter uma cópia na sua conta e, em seguida, clone-o localmente.

  ```bash
  git clone git@github.com:<your Github handle>/transformers.git
  cd transformers
  ```

2. Adicione o repositório Transformers como um remote chamado `upstream`. `origin` aponta para o seu fork e `upstream` aponta para a fonte da verdade. Isso permite sincronizar seu `main` local antes de fazer push para `origin` e abrir um PR.

  ```bash
  git remote add upstream https://github.com/huggingface/transformers.git
  git remote -v
  # origin    git@github.com:<your Github handle>/transformers.git (fetch)
  # origin    git@github.com:<your Github handle>/transformers.git (push)
  # upstream  https://github.com/huggingface/transformers.git (fetch)
  # upstream  https://github.com/huggingface/transformers.git (push)
  ```

3. Mantenha seu fork atualizado e crie um branch para trabalhar. Você também pode sincronizar seu fork pela interface do GitHub com o botão **Sync fork**.

  ```bash
  git checkout main && git pull upstream main && git push origin main
  git switch -c a-descriptive-name-for-my-branch
  ```

4. Instale a biblioteca em modo editável. Use `[dev]` para a maioria das contribuições, pois inclui as ferramentas de desenvolvimento necessárias para verificações de estilo e qualidade. Use `[torch,testing]` para contribuições de modelos, ou `[quality]` para alterações apenas na documentação e correções pequenas quando o conjunto completo de dependências de desenvolvimento não for necessário.

  ```bash
  pip install -e ".[dev]"

  # for model contributions
  pip install -e ".[torch,testing]"

  # for docs-only changes and small fixes
  pip install -e ".[quality]"
  ```

### Windows

No Windows, a menos que você esteja usando [WSL](https://learn.microsoft.com/en-us/windows/wsl/), configure o git para converter as quebras de linha `CRLF` em `LF`.

```bash
git config core.autocrlf input
```

Uma forma de executar o comando `make` no Windows é com o MSYS2.

1. [Baixe o MSYS2](https://www.msys2.org/) (assumimos que ele está instalado em `C:\msys64`).
2. Abra a linha de comando `C:\msys64\msys2.exe` (ela deve estar disponível no menu **Iniciar**).
3. Execute no shell: `pacman -Syu` e instale `make` com `pacman -S make`.
4. Adicione `C:\msys64\usr\bin` à variável de ambiente PATH.

Agora você pode usar `make` em qualquer terminal (PowerShell, cmd.exe, etc.).

## Abrindo problemas

Use os [modelos](https://github.com/huggingface/transformers/tree/main/.github/ISSUE_TEMPLATE) de issue e verifique se o problema não foi reportado anteriormente (use a barra de pesquisa do GitHub em Issues). Um relatório de bug deve ser sobre um bug no Transformers, não no seu próprio código, e deve afetar o uso real e checkpoints reais; um “bug teórico” encontrado ao ler o código que requer uma configuração muito não padrão para ser acionado não será triado, a menos que seja uma questão de segurança. Inclua um script curto e autossuficiente que reproduza o bug na versão mais recente ou no `main`, usando um checkpoint publicado ou a configuração padrão. Relatórios de bug sem um reprodutor executável não serão triados.

Se você não tiver certeza de que o bug está no seu código ou na biblioteca, pergunte primeiro no [fórum](/static-proxy?url=https%3A%2F%2Fdiscuss.huggingface.co%2F) ou no [Discord](https://discord.com/invite/hugging-face-879548962464493619). Isso ajuda a manter o GitHub focado em problemas acionáveis da biblioteca.

## Adicionando um novo modelo

Adicionar um modelo ao Transformers torna-o disponível para qualquer pessoa carregar e fazer fine-tuning ou executar inferência. Antes de iniciar a implementação, isole as diferenças entre a sua arquitetura e os modelos de estado da arte recentes que já estão no Transformers. Explique essas diferenças na issue ou no PR para que os revisores possam entender rapidamente quais desafios o modelo traz, quais partes podem reutilizar padrões existentes e o que deve ser padronizado entre os modelos.

Siga os guias abaixo.

1. [Adicionar um modelo com Transformers modulares](https://github.com/huggingface/transformers/blob/main/docs/source/en/modular_transformers.md) — implemente o modelo usando o arquivo modular e gere os arquivos de modelagem independentes.
2. [Gerar docstrings automaticamente](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) — use o decorador `@auto_docstring` para gerar docstrings consistentes sem código repetitivo.
3. [Testes](https://github.com/huggingface/transformers/blob/main/docs/source/en/testing.md) — escreva e execute testes de modelo para verificar a correção e manter a contribuição mantida. Para modelos de linguagem causal, herde do tester de LM causal sempre que possível. Priorize testes de integração, pois eles verificam o caminho completo do processador, tokenizador e modelo contra checkpoints reais.
4. [Regras de estrutura do modelo](https://github.com/huggingface/transformers/blob/main/docs/source/en/modeling_rules.md) — verifique se seus arquivos passam pelas regras estáticas de estrutura do modelo aplicadas por `make typing`.

Algumas adições de modelos exigem trabalho extra de integração.

- [Adicione componentes de processamento de visão](https://github.com/huggingface/transformers/blob/main/docs/source/en/add_vision_processing_components.md) se o seu modelo exigir entradas de imagem ou vídeo.
- [Carregamento dinâmico de pesos](https://github.com/huggingface/transformers/blob/main/docs/source/en/weightconverter.md) quando os nomes dos parâmetros do checkpoint publicado não correspondem à implementação do Transformers.

### Linha do tempo de adição de modelos

Existem quatro prazos para a inclusão de modelos, dependendo do contribuidor do modelo e da demanda da comunidade por uma arquitetura.

- Integração no dia zero: disponibilizar o modelo no Transformers no dia do lançamento, com um novo release de versão. Fornecemos suporte para as principais funcionalidades essenciais (quantização, FlashAttention, KV-cache, etc.), revisamos rascunhos iniciais e, dependendo dos prazos, também podemos cuidar da implementação do modelo.

  Envie um e-mail para transformers@huggingface.co algumas semanas antes, especialmente no caso de arquiteturas inéditas. Iteraremos com você em um fork privado até que seu checkpoint e seu lançamento estejam prontos.

- Integração na mesma semana: modelos de alta demanda geralmente são integrados em até uma semana, mesmo quando o autor não entra em contato.

  Abra uma issue com o [new model template](https://github.com/huggingface/transformers/issues/new?assignees=&labels=New+model&projects=&template=new-model-addition.yml) para solicitar um. Issues com mais atividade sobem mais rápido na fila.

- Integração pós-lançamento: modelos sem forte demanda, ou que não temos capacidade para assumir, são lançados após a liberação upstream.

  Contribuintes externos podem abrir um PR para um novo modelo diretamente, com ou sem uma issue. Antes de começar, verifique as issues abertas de ["New model"](https://github.com/huggingface/transformers/issues?q=is%3Aopen+is%3Aissue+label%3A%22New+model%22) e os PRs abertos para garantir que ninguém já esteja adicionando-o. Faremos a revisão e orientaremos você durante o processo.

- Lançamento com foco no Hub: publique seu modelo diretamente no Hub por meio do suporte a [remote-code](https://github.com/huggingface/transformers/blob/main/docs/source/en/models.md#custom-models) do Transformers, sem a necessidade de um PR upstream.

  Modelos populares com abordagem Hub-first geralmente são integrados ao Transformers posteriormente, o que habilita documentação de primeira classe, manutenção e otimização. A abordagem Hub-first é a forma de menor atrito para adicionar um modelo. No entanto, ela pode ser mais frágil se o modelo exigir conversão de pesos ou outros problemas de compatibilidade reversa.

## Docs

Para a referência de API gerada a partir dos arquivos de origem, use o decorador [`@auto_docstring`](https://github.com/huggingface/transformers/blob/main/docs/source/en/auto_docstring.md) quando aplicável. Consulte o [README](https://github.com/huggingface/transformers/blob/main/docs/README.md) da documentação para mais detalhes sobre como editar a documentação e a sintaxe que utilizamos.

