Contribuindo para os projetos de código aberto da Ultralytics#

Bem-vindo! Estamos entusiasmados por estares a considerar contribuir para os nossos projetos de open-source da Ultralytics. A tua participação não só ajuda a melhorar a qualidade dos nossos repositórios, como também beneficia toda a comunidade de computer vision. Este guia fornece 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 contribuintes devem cumprir o nosso Code of Conduct. Respeito, gentileza e profissionalismo estão no centro da nossa comunidade.

🚀 Contribuindo via Pull Requests#

Apreciamos imenso contribuições sob a forma de pull requests (PRs). Para tornar o processo de revisão o mais fluído possível, segue estes passos:

1. Fork the repository: Começa por fazer um fork do repositório Ultralytics relevante (por exemplo, ultralytics/ultralytics) para a tua conta GitHub.
2. Create a branch: Cria uma nova branch no teu repositório com fork com um nome claro e descritivo que reflita as tuas alterações (por exemplo, fix-issue-123, add-feature-xyz).
3. Faça suas alterações: Implemente suas melhorias ou correções. Garanta que seu código siga as diretrizes de estilo do projeto e não introduza novos erros ou avisos.
4. Testa as tuas alterações: Antes de submeter, testa as tuas alterações localmente para confirmar que funcionam conforme esperado e não causam regressions. Adiciona testes se estiveres a introduzir novas funcionalidades.
5. Commit your changes: 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 da issue (por exemplo, Fix #123: Corrected calculation error.).
6. Create a pull request: Submete 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 a explicar o propósito e o âmbito das tuas alterações.

📝 Assinatura do CLA#

Antes de podermos fazer o merge do teu pull request, tens de assinar o nosso Contributor License Agreement (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 AGPL-3.0 license.

Após enviar seu pull request, o bot do CLA te guiará pelo processo de assinatura. Para assinar o CLA, basta adicionar um comentário no seu PR declarando:

I have read the CLA Document and I sign the CLA

✍️ Docstrings no estilo Google#

Ao adicionar novas funções ou classes, inclui Google-style docstrings para obter uma documentação clara e padronizada. Coloca sempre tanto a entrada quanto a saída types 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 Continuous Integration do GitHub Actions (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. Revisa a saída da CI e resolve quaisquer problemas que surjam.

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

Ao contribuir com código para projetos da Ultralytics, mantenha estas melhores práticas em mente:

• Evite a duplicação de código: Reutilize o código existente sempre que possível e minimize argumentos desnecessários.
• Faça alterações menores e focadas: Concentre-se em modificações direcionadas em vez de mudanças em grande escala.
• Simplifique sempre que possível: Procure oportunidades para simplificar o código ou remover partes desnecessárias.
• Considere a compatibilidade: Antes de fazer alterações, considere se elas podem quebrar o 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 tests para novas funcionalidades para garantir que funcionam conforme esperado.

👀 Revisando Pull Requests#

Revisar pull requests é outra maneira valiosa de contribuir. Ao revisar PRs:

• Verifique se há testes unitários: Confirme que o PR inclui testes para novas funcionalidades ou alterações.
• Revê as atualizações da documentação: Certifica-te de que a documentation é atualizada para refletir as alterações.
• Avalia o impacto no desempenho: Considera como as alterações podem afetar o performance.
• Verifica os testes de CI: Confirma que todos os Continuous Integration tests estão a passar.
• Forneça feedback construtivo: Ofereça feedback específico e claro sobre quaisquer problemas ou preocupações.
• Reconheça o esforço: Reconheça o trabalho do autor para manter uma atmosfera colaborativa positiva.

🐞 Relatando Bugs#

Damos muito valor aos relatórios de bugs, pois ajudam-nos a melhorar a qualidade e a fiabilidade dos nossos projetos. Ao reportar um bug através do GitHub Issues:

• Verifique se já existem issues: Pesquise primeiro para ver se o bug já foi relatado.
• Fornece um Minimum Reproducible Example: Cria um pequeno snippet de código autónomo que reproduza consistentemente o problema. Isto é crucial para uma depuração eficiente.
• Descreve o ambiente: Especifica o teu sistema operativo, versão do Python, versões de bibliotecas relevantes (por exemplo, torch, ultralytics) e hardware (CPU/GPU).
• Explique o comportamento esperado vs. real: Afirme claramente o que você esperava que acontecesse e o que realmente ocorreu. Inclua quaisquer mensagens de erro ou tracebacks.

📜 Licença#

A Ultralytics utiliza a GNU Affero General Public License v3.0 (AGPL-3.0) para os seus repositórios. Esta licença promove a openness, a transparency e a collaborative improvement no desenvolvimento de software. Garante que todos os utilizadores têm a liberdade de usar, modificar e partilhar o software, promovendo uma comunidade forte de colaboração e inovação.

Encorajamos todos os contribuintes a familiarizarem-se com os termos da AGPL-3.0 license para contribuírem de forma eficaz e ética para a comunidade open-source da Ultralytics.

🌍 Tornando seu projeto YOLO de código aberto sob a AGPL-3.0#

Estás a utilizar modelos ou código do Ultralytics YOLO no teu projeto? A AGPL-3.0 license exige que toda a tua obra derivada também seja open-source sob a AGPL-3.0. Isto garante que as modificações e os projetos maiores criados com base em fundações open-source permaneçam abertos.

Por que a conformidade com a AGPL-3.0 é importante#

• Mantém o software aberto: Garante que melhorias e trabalhos derivados beneficiem a comunidade.
• Requisito legal: Usar código licenciado sob a AGPL-3.0 vincula seu projeto aos seus termos.
• Promove a colaboração: Encoraja o compartilhamento e a transparência.

Se preferires não tornar o teu projeto open-source, considera obter uma Enterprise License.

Como cumprir com a AGPL-3.0#

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

1. Escolha seu ponto de partida:

   • Faz fork do Ultralytics YOLO: Faz diretamente o fork do Ultralytics YOLO repository se criares algo muito baseado nele.
   • Usa o template da Ultralytics: Começa com o Ultralytics template repository para uma configuração limpa e modular que integra o YOLO.

2. Licencie seu projeto:

   • Adiciona um ficheiro LICENSE contendo o texto completo da AGPL-3.0 license.
   • Adicione um aviso no topo de cada arquivo de código-fonte indicando a licença.

3. Publique seu código-fonte:

   • Torne o código-fonte de todo o seu projeto publicamente acessível (por exemplo, no GitHub). Isso inclui:
     • A aplicação ou sistema maior completo que incorpora o modelo ou código YOLO.
     • Quaisquer modificações feitas no código original da Ultralytics YOLO.
     • Scripts para treinamento, validação e inferência.
     • Model weights se modificados ou ajustados (fine-tuned).
     • Configuration files, configurações de ambiente (requirements.txt, Dockerfiles).
     • Código de backend e frontend se fizer parte de uma web application.
     • Quaisquer third-party libraries que tenhas modificado.
     • Training data se necessário para executar/reentrenar e redistribuível.

4. Documente claramente:

   • Atualiza o teu README.md para declarar que o projeto está licenciado sob a AGPL-3.0.
   • Inclua instruções claras sobre como configurar, construir e executar seu projeto a partir do código-fonte.
   • Atribui os créditos devidos ao Ultralytics YOLO, fazendo ligação para o original repository. 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 Ultralytics Template Repository para ver uma estrutura de exemplo prática:

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

Seguindo estas diretrizes, você garante a conformidade com a AGPL-3.0, apoiando 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 open-source da Ultralytics. A tua participação é essencial para moldar o futuro do nosso software e construir uma comunidade vibrante de inovação e colaboração. Quer estejas a melhorar código, a reportar bugs 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 em fazer avançar a tecnologia de object detection. Juntos, vamos continuar a crescer e a inovar nesta emocionante jornada open-source.

FAQ#

Por que devo contribuir para os repositórios de código aberto da Ultralytics YOLO?#

Contribuir para os repositórios open-source do Ultralytics YOLO melhora o software, tornando-o mais robusto e rico em funcionalidades para toda a comunidade. As contribuições podem incluir melhorias de código, correções de bugs, melhorias na documentação e a implementação de novas funcionalidades. Além disso, contribuir permite-te colaborar com outros programadores experientes e especialistas na área, melhorando as tuas próprias competências e reputação. Para obter detalhes sobre como começar, consulta a secção Contributing via Pull Requests.

Como assino o Contrato de Licença de Contribuidor (CLA) para a Ultralytics YOLO?#

Para assinar o Contrato de Licença de Contribuidor (CLA), siga as instruções fornecidas pelo bot do CLA após enviar seu pull request. Este processo garante que suas contribuições estejam devidamente licenciadas sob a licença AGPL-3.0, mantendo a integridade legal do projeto de código aberto. Adicione um comentário no seu pull request declarando:

I have read the CLA Document and I sign the CLA

Para mais informações, consulta a secção CLA Signing.

O que são docstrings no estilo Google e por que são exigidas para contribuições à Ultralytics YOLO?#

As Google-style docstrings fornecem documentação clara e concisa para funções e classes, melhorando a legibilidade e a manutenibilidade do código. Estas docstrings descrevem o propósito da função, argumentos e valores de retorno com regras de formatação específicas. Ao contribuir para o Ultralytics YOLO, seguir as Google-style docstrings garante que as tuas adições estão bem documentadas e são facilmente compreendidas. Para exemplos e diretrizes, visita a secção Google-Style Docstrings.

Como posso garantir que as minhas alterações passem nos testes de CI do GitHub Actions?#

Antes de o teu pull request poder ser integrado, deve passar por todos os testes de Integração Contínua (CI) do GitHub Actions. Estes testes incluem linting, testes unitários e outras verificações para garantir que o código cumpre os padrões de qualidade do projeto. Revê a saída da CI e corrige quaisquer problemas. Para obter informações detalhadas sobre o processo de CI e dicas de resolução de problemas, consulta a secção GitHub Actions CI Tests.

Como posso reportar um bug nos repositórios do Ultralytics YOLO?#

Para reportar um bug, fornece um Minimum Reproducible Example claro e conciso juntamente com o teu relatório de bug. Isto ajuda os programadores a identificar e corrigir rapidamente o problema. Certifica-te de que o teu exemplo é mínimo, mas suficiente para replicar o problema. Para obter passos mais detalhados sobre como reportar bugs, consulta a secção Reporting Bugs.

O que significa a licença AGPL-3.0 se eu utilizar o Ultralytics YOLO no meu próprio projeto?#

Se utilizares código ou modelos do Ultralytics YOLO (licenciados sob a AGPL-3.0) no teu projeto, a licença AGPL-3.0 exige que todo o teu projeto (a obra derivada) também seja licenciado sob a AGPL-3.0 e que o seu código-fonte completo seja disponibilizado publicamente. Isto garante que a natureza open-source do software é preservada em todas as suas derivadas. Se não conseguires cumprir estes requisitos, precisas de obter uma Enterprise License. Vê a secção Open-Sourcing Your Project para obter detalhes.