# Experimental

Este diretório contém um espaço mínimo e claramente separado para iteração rápida em novas ideias.

> [!WARNING]
> **Contrato de estabilidade:** Qualquer coisa sob `trl.experimental` pode ser alterada ou removida em *qualquer* versão (incluindo versões de correção) sem aviso prévio de descontinuação. Não dependa dessas APIs para cargas de trabalho de produção.

## Caminho de Promoção (Simples)

1. **Prototipe fora do repositório principal:** Comece o desenvolvimento no seu próprio fork ou em um repositório separado para iterar rapidamente.
2. **Inclusão experimental:** Quando estiver pronto para usuários iniciais, mova a ideia para `trl.experimental.<feature>`.
3. **Melhorar:** Adicionar testes, uma breve documentação/exemplo e demonstrar o uso.
4. **Elevar:** Uma vez que a API se mostre estável e haja interesse ou adoção claros por parte da comunidade, mova-a para `trl.<feature>` (módulo estável).

## Remoção

Experimental é uma área de preparação, não armazenamento de longo prazo: um recurso é promovido ou removido. A remoção não exige um ciclo de depreciação, conforme estabelecido no contrato de estabilidade acima. O código permanece disponível no histórico do git, e a entrada do [índice de papers](paper_index) permanece, apontando para a última liberação que incluiu a implementação.

Nenhum limite dispara uma remoção. Trata-se de uma decisão de julgamento, tomada na pull request de remoção, com os números à frente de todos. O que esse julgamento pondera:

- **Uso.** Telemetria, tags do Hub e respostas na pull request ou em uma thread de discussão. Nenhuma delas é conclusiva por si só, mas o silêncio de todas elas é um sinal forte.
- **Problemas externos e solicitações de pull que surgem da execução do recurso**, em oposição aos relatórios gerados pela análise do código.
- **Se um treinador estável já cobre isso.** Se sim, isso pesa mais que o uso.
- **Custo.** Tempo de CI, manutenção, carga de triagem.
- **Consumidores a jusante.** Bibliotecas que importam.
- **Proprietário.** Alguém que deseja que o item seja promovido e está disposto a realizar o trabalho.
- **Tempo de existência.** Se já está disponível há tempo suficiente para que a comunidade o encontre e o teste.

## Perguntas frequentes

**Por que não usar apenas branches?** Porque branches não são enviados aos usuários; o código experimental dentro do pacote permite que os primeiros adotadores experimentem e deem feedback.

**Essas APIs podem mudar ou desaparecer sem aviso?** Sim. Qualquer coisa dentro de `trl.experimental` pode mudar ou desaparecer em *qualquer* release.

**Devo usar isso em produção?** Somente se você estiver confortável em atualizar seu código rapidamente quando as coisas mudarem.

**Os mantenedores corrigirão rapidamente os problemas em `trl.experimental`?** Não necessariamente. O módulo experimental é um espaço para novas ideias, e os mantenedores podem não priorizar correções de bugs ou solicitações de recursos nele. Os problemas podem permanecer sem resolução até (ou a menos que) o recurso seja promovido para a API estável.

**Contribuí uma implementação de artigo. Ela pode ser removida?** Sim. Qualquer coisa sob `trl.experimental` pode ser removida, incluindo implementações de artigos. Se isso acontecer, a entrada do [índice de artigos](paper_index) permanece e aponta para o último lançamento que incluiu o código.

**Como silenciar a notificação de tempo de execução?**

Use: `export TRL_EXPERIMENTAL_SILENCE=1`.

