Contribuir para projetos de código aberto da Ultralytics#

Boas-vindas! Ficamos muito contentes por estares a considerar contribuir para os nossos projetos de Ultralytics de código aberto. A tua participação 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 apresenta diretrizes 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 têm de cumprir o nosso Código de Conduta. Respeito, gentileza e profissionalismo são a base da nossa comunidade.

Contribuir por meio de pull requests#

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

1. Cria um fork do repositório: começa por criar um fork do repositório pertinente da Ultralytics (por exemplo, ultralytics/ultralytics) para a tua conta do GitHub.
2. Cria uma ramificação: cria uma nova ramificação no teu repositório bifurcado, 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 nem avisos.
4. Testa as tuas alterações: antes de as enviares, testa-as localmente para confirmar que funcionam como esperado e não causam regressões. Adiciona testes se estiveres a introduzir novas funcionalidades.
5. Faz commit das tuas alterações: faz commit das tuas alterações com mensagens concisas e descritivas. Se as tuas alterações resolverem um problema específico, inclui o número da issue (por exemplo, Fix #123: Corrected calculation error.).
6. Cria um pull request: envia um pull request da tua ramificação para a ramificação main do repositório original da Ultralytics. Inclui um título claro e uma descrição detalhada que explique o objetivo e o âmbito das tuas alterações.

Instalação para desenvolvimento#

Clona o teu fork (ou o repositório principal) e instala-o em modo editável (-e) para que Python execute os teus ficheiros locais e detete todas as alterações sem ser necessário reinstalar:

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

Para fazer com que outro projeto dependa de um fork em vez do pacote do PyPI, aponta o pip ou requirements.txt para a ramificação do fork:

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

Alterações à documentação#

O código-fonte da documentação encontra-se em docs/en/. A partir da raiz do repositório, instala as dependências de desenvolvimento e executa a validação rigorosa 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 dinâmica mais rápida de páginas que não usam macros, executa zensical serve.

Assinatura do CLA#

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

Depois de enviares o teu pull request, o bot do CLA vai guiar-te pelo processo de assinatura. Para assinares o CLA, basta adicionares um comentário ao teu PR com o seguinte texto:

I have read the CLA Document and I sign the CLA

Docstrings ao estilo do Google#

Ao adicionares novas funções ou classes, inclui docstrings ao estilo do Google para uma documentação clara e padronizada. Coloca sempre os 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 com GitHub Actions#

Todos os pull requests têm de passar nos testes de GitHub Actions de integração contínua (CI) antes de poderem ser integrados. Estes testes incluem análise estática, testes unitários e outras verificações para garantir que as tuas alterações cumprem os padrões de qualidade do projeto. Analisa os resultados da CI e resolve quaisquer problemas que surjam.

Boas práticas para contribuições de código#

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

• Evita duplicar código: reutiliza o código existente sempre que possível e minimiza os argumentos desnecessários.
• Faz alterações menores e focadas: privilegia modificações específicas em vez de alterações em grande escala.
• Simplifica sempre que possível: procura oportunidades para simplificar o código ou remover partes desnecessárias.
• Tem em conta a compatibilidade: antes de fazeres alterações, considera se estas podem quebrar código existente que usa 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 como esperado.

Revisão de pull requests#

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

• Verifica se há testes unitários: confirma se 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 podem afetar o desempenho.
• Verifica os testes de CI: confirma se todos os testes de integração contínua estão a passar.
• Dá feedback construtivo: apresenta comentários específicos e claros sobre quaisquer problemas ou preocupações.
• Reconhece o esforço: valoriza o trabalho do autor para manter um ambiente colaborativo positivo.

Comunicar erros#

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

• Verifica os problemas existentes: pesquisa primeiro para saber se o erro já foi comunicado.
• Fornece um Exemplo Mínimo Reproduzível: cria um pequeno trecho de código autónomo que reproduza o problema de forma consistente. Isto é essencial para depurar com eficiência.
• 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 comportamento real: indica claramente o que esperavas que acontecesse e o que aconteceu na realidade. Inclui quaisquer mensagens de erro ou rastreamentos de pilha.

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 usar, modificar e partilhar o software, fomentando 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.

Torna o teu projeto YOLO de código aberto ao abrigo da AGPL-3.0#

Estás a utilizar modelos ou código Ultralytics YOLO no teu projeto? A licença AGPL-3.0 exige que todo o teu trabalho derivado também seja disponibilizado como código aberto ao abrigo da AGPL-3.0. Isto garante que as modificações e os projetos maiores criados com base em fundações de código aberto permaneçam abertos.

Porque é importante cumprir a AGPL-3.0#

• Mantém o software aberto: garante que as melhorias e os trabalhos derivados beneficiam a comunidade.
• Obrigação legal: a utilização de código licenciado ao abrigo da AGPL-3.0 sujeita 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 Empresarial.

Como cumprir a AGPL-3.0#

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

1. Escolhe o teu ponto de partida:

   • Faz fork da Ultralytics YOLO: faz fork diretamente do repositório Ultralytics YOLO se estiveres a criar algo muito baseado nele.
   • Usa o modelo da Ultralytics: começa pelo repositório de modelos da Ultralytics para obter uma estrutura organizada e modular que integre YOLO.

2. Licencia o teu projeto:

   • Adiciona um ficheiro LICENSE com o texto integral da licença AGPL-3.0.
   • Adiciona um aviso no início de cada ficheiro de código-fonte a indicar a licença.

3. Publica o teu código-fonte:

   • Disponibiliza publicamente o código-fonte completo do teu projeto (por exemplo, no GitHub). Isto inclui:
     • A aplicação ou o sistema completo de maior dimensão que incorpora o modelo ou o código YOLO.
     • Quaisquer modificações feitas ao código original da Ultralytics YOLO.
     • Scripts para treino, validação e inferência.
     • Pesos do modelo, caso tenham sido modificados ou ajustados por fine-tuning.
     • 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/treinar novamente e puderem ser redistribuídos.

4. Documenta claramente:

   • Atualiza o teu README.md para indicar que o projeto está licenciado ao abrigo da AGPL-3.0.
   • Inclui instruções claras para configurar, compilar e executar o teu projeto a partir do código-fonte.
   • Atribui corretamente os créditos à Ultralytics YOLO, 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 Modelos 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 poderosas como a Ultralytics YOLO.

Conclusão#

Obrigado pelo teu interesse em contribuir para os projetos YOLO de código aberto da Ultralytics. 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 empenho em fazer avançar a tecnologia de deteção de objetos. Juntos, vamos continuar a crescer e a inovar nesta entusiasmante jornada de código aberto.

Perguntas frequentes#