Contribuir para projetos de código aberto da Ultralytics#

Bem-vindo! Ficamos muito contentes por considerares contribuir para os nossos projetos de Ultralytics de código aberto. O teu envolvimento não só ajuda a melhorar a qualidade dos nossos repositórios, como também beneficia toda a comunidade de visão computacional. Este guia fornece orientações claras e boas práticas para te ajudar a começar.

Código de Conduta#

Para garantir um ambiente acolhedor e inclusivo para todos, todos os contribuidores devem cumprir o nosso Código de Conduta. Respeito, gentileza e profissionalismo estão no centro da nossa comunidade.

Contribuindo por meio de PR#

Agradecemos muito as contribuições sob a forma de pedidos de pull request (PRs). Para tornar o processo de revisão o mais simples possível, segue estes passos:

1. Faz um fork do repositório: Começa por fazer fork do repositório relevante da Ultralytics (por exemplo, ultralytics/ultralytics) para a tua conta do GitHub.
2. Cria uma branch: Cria uma nova branch no teu repositório forkado, com um nome claro e descritivo que reflita as tuas alterações (por exemplo, fix-issue-123, add-feature-xyz).
3. Faz as tuas alterações: Implementa as tuas melhorias ou correções. Garante que o teu código cumpre as diretrizes de estilo do projeto e não introduz novos erros ou avisos.
4. Testa as tuas alterações: Antes de enviar, testa as tuas alterações localmente para confirmar que funcionam conforme esperado e não causam regressões. Adiciona testes se estiveres a introduzir nova funcionalidade.
5. Faz commit das tuas alterações: Faz commit das tuas alterações com mensagens de commit concisas e descritivas. Se as tuas alterações resolverem um problema específico, inclui o número do problema (por exemplo, Fix #123: Corrected calculation error.).
6. Cria um pull request: Envia um pull request da tua branch para a branch main do repositório original da Ultralytics. Fornece um título claro e uma descrição detalhada que explique o objetivo e o âmbito das tuas alterações.

Instalação para Desenvolvimento#

Clone o teu fork (ou o repositório principal) e instale-o em modo editável (-e) para que o Python execute os teus arquivos locais e capte cada alteração sem reinstalar:

git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .

Para fazer outro projeto depender de um fork em vez do pacote PyPI, aponte o pip ou o requirements.txt para a branch do fork:

git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branch

Alterações na Documentação#

O código-fonte da documentação está em docs/en/. A partir da raiz do repositório, instala as dependências de desenvolvimento e executa a validação estrita completa antes de abrir um PR:

uv pip install -e ".[dev]"
python docs/build_docs.py

A validação prepara referências geradas, macros e páginas de comparação antes de executar zensical build --strict. Para uma pré-visualização ao vivo mais rápida de páginas que não utilizam macros, executa zensical serve.

Assinatura do CLA#

Antes de podermos fazer merge do teu pull request, tens de assinar o nosso Acordo de Licença do Contribuidor (CLA). Este acordo legal garante que as tuas contribuições estão devidamente licenciadas, permitindo que o projeto continue a ser distribuído sob a licença AGPL-3.0.

Depois de enviares o teu pull request, o bot do CLA irá orientar-te durante o processo de assinatura. Para assinares o CLA, basta adicionares um comentário no teu PR a indicar:

I have read the CLA Document and I sign the CLA

Docstrings no Estilo do Google#

Ao adicionares novas funções ou classes, inclui docstrings ao estilo Google para obteres uma documentação clara e padronizada. Coloca sempre types de entrada e de saída entre parênteses (por exemplo, (bool), (np.ndarray)).

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

Testes de CI do GitHub Actions#

Todos os pull requests devem passar nos testes de GitHub Actions de Integração Contínua (CI) antes de poderem ser integrados. Estes testes incluem linting, testes unitários e outras verificações para garantir que as tuas alterações cumprem os padrões de qualidade do projeto. Revê o resultado do CI e resolve quaisquer problemas que surjam.

Melhores Práticas para Contribuições de Código#

Ao contribuíres com código para projetos da Ultralytics, tem em mente estas boas práticas:

• Evita a duplicação de código: Reutiliza o código existente sempre que possível e minimiza os argumentos desnecessários.
• Faz alterações menores e focadas: Concentra-te em modificações específicas em vez de alterações de grande escala.
• Simplifica quando possível: Procura oportunidades para simplificar o código ou remover partes desnecessárias.
• Considera a compatibilidade: Antes de fazer alterações, considera se estas poderão quebrar código existente que utilize a Ultralytics.
• Usa uma formatação consistente: Ferramentas como o Ruff Formatter podem ajudar a manter a consistência estilística.
• Adiciona testes adequados: Inclui testes para novas funcionalidades, para garantir que funcionam conforme esperado.

Revisão de PR#

Rever pull requests é outra forma valiosa de contribuir. Ao rever PRs:

• Verifica os testes unitários: Confirma que o PR inclui testes para novas funcionalidades ou alterações.
• Revê as atualizações da documentação: Garante que a documentação foi atualizada para refletir as alterações.
• Avalia o impacto no desempenho: Considera como as alterações poderão afetar o desempenho.
• Verifica os testes de CI: Confirma que todos os testes de Integração Contínua estão a passar.
• Fornece feedback construtivo: Dá feedback específico e claro sobre quaisquer problemas ou preocupações.
• Reconhece o esforço: Agradece o trabalho do autor para manter uma atmosfera colaborativa positiva.

Reportando Erros#

Valorizamos muito os relatórios de erros, pois ajudam-nos a melhorar a qualidade e a fiabilidade dos nossos projetos. Ao comunicares um erro através do GitHub Issues:

• Verifica os problemas existentes: Pesquisa primeiro para ver se o erro já foi comunicado.
• Fornece um Exemplo Mínimo Reproduzível: Cria um pequeno trecho de código autónomo que reproduza consistentemente o problema. Isto é essencial para uma depuração eficiente.
• Descreve o ambiente: Especifica o teu sistema operativo, a versão do Python, as versões das bibliotecas relevantes (por exemplo, torch, ultralytics) e o hardware (CPU/GPU).
• Explica o comportamento esperado e o real: Indica claramente o que esperavas que acontecesse e o que ocorreu na realidade. Inclui quaisquer mensagens de erro ou tracebacks.

Licença#

A Ultralytics utiliza a Licença Pública Geral Affero GNU v3.0 (AGPL-3.0) nos seus repositórios. Esta licença promove a abertura, a transparência e a melhoria colaborativa no desenvolvimento de software. Garante que todos os utilizadores têm liberdade para utilizar, modificar e partilhar o software, promovendo uma comunidade forte de colaboração e inovação.

Incentivamos todos os contribuidores a familiarizarem-se com os termos da licença AGPL-3.0 para contribuírem de forma eficaz e ética para a comunidade de código aberto da Ultralytics.

Tornando o Teu Projeto YOLO Open-Source Sob a AGPL-3.0#

Utilizas modelos ou código YOLO da Ultralytics no teu projeto? A licença AGPL-3.0 exige que todo o teu trabalho derivado também seja disponibilizado como código aberto sob a AGPL-3.0. Isto garante que as modificações e os projetos maiores construídos sobre bases de código aberto permanecem abertos.

Porque é importante cumprir a AGPL-3.0#

• Mantém o software aberto: Garante que as melhorias e os trabalhos derivados beneficiam a comunidade.
• Requisito legal: A utilização de código licenciado sob a AGPL-3.0 vincula o teu projeto aos respetivos termos.
• Promove a colaboração: Incentiva a partilha e a transparência.

Se preferires não disponibilizar o teu projeto como código aberto, considera obter uma Licença Enterprise.

Como cumprir a AGPL-3.0#

Cumprir significa disponibilizar publicamente o código-fonte completo correspondente do teu projeto sob a licença AGPL-3.0.

1. Escolhe o teu ponto de partida:

   • Faz fork do YOLO da Ultralytics: Faz fork diretamente do repositório YOLO da Ultralytics se estiveres a construir algo estreitamente baseado nele.
   • Usa o template da Ultralytics: Começa pelo repositório de template da Ultralytics para obteres uma configuração limpa e modular que integre YOLO.

2. Licencia o teu projeto:

   • Adiciona um ficheiro LICENSE que contenha o texto integral da licença AGPL-3.0.
   • Adiciona um aviso no topo de cada ficheiro de código-fonte a indicar a licença.

3. Publica o teu código-fonte:

   • Torna todo o código-fonte do teu projeto publicamente acessível (por exemplo, no GitHub). Isto inclui:
     • A aplicação ou o sistema maior completo que incorpora o modelo ou código YOLO.
     • Quaisquer modificações feitas ao código YOLO original da Ultralytics.
     • Scripts de treino, validação e inferência.
     • Pesos do modelo se tiverem sido modificados ou ajustados.
     • Ficheiros de configuração, configurações do ambiente (requirements.txt, Dockerfiles).
     • Código de backend e frontend, se fizer parte de uma aplicação web.
     • Quaisquer bibliotecas de terceiros que tenhas modificado.
     • Dados de treino se forem necessários para executar ou voltar a treinar o modelo e forem redistribuíveis.

4. Documenta claramente:

   • Atualiza o teu README.md para indicar que o projeto está licenciado sob a AGPL-3.0.
   • Inclui instruções claras sobre como configurar, compilar e executar o teu projeto a partir do código-fonte.
   • Atribui corretamente os créditos ao YOLO da Ultralytics, com uma ligação para o repositório original. Exemplo:

     This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.

Exemplo de estrutura de repositório#

Consulta o Repositório de Template da Ultralytics para veres um exemplo prático de estrutura:

my-yolo-project/
│
├── LICENSE               # Full AGPL-3.0 license text
├── README.md             # Project description, setup, usage, license info & attribution
├── pyproject.toml        # Dependencies (or requirements.txt)
├── scripts/              # Training/inference scripts
│   └── train.py
├── src/                  # Your project's source code
│   ├── __init__.py
│   ├── data_loader.py
│   └── model_wrapper.py  # Code interacting with YOLO
├── tests/                # Unit/integration tests
├── configs/              # YAML/JSON config files
├── docker/               # Dockerfiles, if used
│   └── Dockerfile
└── .github/              # GitHub specific files (e.g., workflows for CI)
    └── workflows/
        └── ci.yml

Ao seguires estas diretrizes, garantes o cumprimento da AGPL-3.0 e apoias o ecossistema de código aberto que possibilita ferramentas avançadas como o YOLO da Ultralytics.

Conclusão#

Obrigado pelo teu interesse em contribuir para os projetos YOLO de Ultralytics de código aberto. A tua participação é essencial para moldar o futuro do nosso software e construir uma comunidade dinâmica de inovação e colaboração. Quer estejas a melhorar código, a comunicar erros ou a sugerir novas funcionalidades, as tuas contribuições são inestimáveis.

Estamos entusiasmados por ver as tuas ideias ganharem vida e agradecemos o teu compromisso com o avanço da tecnologia de deteção de objetos. Juntos, continuemos a crescer e a inovar nesta emocionante jornada de código aberto.

Perguntas frequentes#