Link to this sectionContribuindo para os projetos de código aberto da Ultralytics#

Welcome! We're thrilled that you're considering contributing to our Ultralytics open-source projects. Your involvement not only helps enhance the quality of our repositories but also benefits the entire computer vision community. This guide provides clear guidelines and best practices to help you get started.

Link to this section🤝 Código de Conduta#

Para garantir um ambiente acolhedor e inclusivo para todos, todos os contribuidores devem seguir nosso Code of Conduct. Respeito, gentileza e profissionalismo estão no coração da nossa comunidade.

Link to this section🚀 Contribuindo via Pull Requests#

Agradecemos muito as contribuições na forma de pull requests (PRs). Para tornar o processo de revisão o mais tranquilo possível, siga estas etapas:

1. Faça um fork do repositório: Comece fazendo um fork do repositório relevante da Ultralytics (por exemplo, ultralytics/ultralytics) para sua conta do GitHub.
2. Crie uma branch: Crie uma nova branch em seu repositório forkado com um nome claro e descritivo que reflita suas 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. Teste suas alterações: Antes de enviar, teste suas alterações localmente para confirmar que funcionam como esperado e não causam regressões. Adicione testes se estiver introduzindo uma nova funcionalidade.
5. Faça commit das suas alterações: Faça commit das suas alterações com mensagens de commit concisas e descritivas. Se suas alterações abordarem um problema específico, inclua o número do problema (por exemplo, Fix #123: Corrected calculation error.).
6. Crie um pull request: Envie um pull request da sua branch para a branch main do repositório original da Ultralytics. Forneça um título claro e uma descrição detalhada explicando o propósito e o escopo das suas alterações.

Link to this section📝 Assinatura do CLA#

Antes que possamos mesclar o seu pull request, você deve assinar nosso Contributor License Agreement (CLA). Este acordo legal garante que as suas contribuições sejam devidamente licenciadas, permitindo que o projeto continue sendo 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:

Link to this section✍️ Docstrings no estilo Google#

Ao adicionar novas funções ou classes, inclua docstrings no estilo Google para uma documentação clara e padronizada. Sempre coloque types de entrada e 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

Link to this section✅ Testes de CI do GitHub Actions#

All pull requests must pass the GitHub Actions Continuous Integration (CI) tests before they can be merged. These tests include linting, unit tests, and other checks to ensure that your changes meet the project's quality standards. Review the CI output and address any issues that arise.

Link to this section✨ 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.
• Use formatação consistente: Ferramentas como o Ruff Formatter podem ajudar a manter a consistência estilística.
• Adicione testes apropriados: Inclua tests para novas funcionalidades a fim de garantir que elas funcionem conforme o esperado.

Link to this section👀 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.
• Revise as atualizações de documentação: Garanta que a documentation esteja atualizada para refletir as mudanças.
• Avalie o impacto no desempenho: Considere como as alterações podem afetar o performance.
• Verifique os testes de CI: Confirme se todos os Continuous Integration tests estão sendo aprovados.
• 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.

Link to this section🐞 Relatando Bugs#

Valorizamos muito os relatórios de bugs, pois nos ajudam a melhorar a qualidade e a confiabilidade de nossos projetos. Ao relatar um bug via GitHub Issues:

• Verifique se já existem issues: Pesquise primeiro para ver se o bug já foi relatado.
• Forneça um Minimum Reproducible Example: Crie um pequeno trecho de código autossuficiente que reproduza o problema de forma consistente. Isso é crucial para uma depuração eficiente.
• Descreva o ambiente: Especifique seu sistema operacional, 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.

Link to this section📜 Licença#

A Ultralytics usa a GNU Affero General Public License v3.0 (AGPL-3.0) para seus repositórios. Esta licença promove a abertura, transparência e melhoria colaborativa no desenvolvimento de software. Ela garante que todos os usuários tenham a liberdade de usar, modificar e compartilhar o software, promovendo uma forte comunidade de colaboração e inovação.

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

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

Usando modelos ou código da Ultralytics YOLO em seu projeto? A licença AGPL-3.0 exige que todo o seu trabalho derivado também seja de código aberto sob a AGPL-3.0. Isso garante que modificações e projetos maiores construídos sobre bases de código aberto permaneçam abertos.

Link to this sectionPor 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 você prefere não abrir o código do seu projeto, considere obter uma Licença Empresarial.

Link to this sectionComo 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:

   • Faça fork da Ultralytics YOLO: Faça fork diretamente do repositório da Ultralytics YOLO se estiver construindo algo muito próximo a ele.
   • Use o modelo da Ultralytics: Comece com o repositório de modelo da Ultralytics para uma configuração limpa e modular integrando YOLO.

2. Licencie seu projeto:

   • Adicione um arquivo LICENSE contendo o texto completo da licença AGPL-3.0.
   • 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.
     • Pesos do modelo se modificados ou ajustados.
     • Configuration files, configurações de ambiente (requirements.txt, Dockerfiles).
     • Código de backend e frontend se fizer parte de uma aplicação web.
     • Quaisquer bibliotecas de terceiros que você modificou.
     • Dados de treinamento se necessários para executar/retreinar e redistribuíveis.

4. Documente claramente:

   • Atualize seu 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.
   • Atribua a Ultralytics YOLO adequadamente, criando um link para o repositório original. Exemplo:

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

Link to this sectionExemplo de estrutura de repositório#

Consulte o Repositório de Modelo da Ultralytics para 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.

Link to this sectionConclusão#

Thank you for your interest in contributing to Ultralytics open-source YOLO projects. Your participation is essential in shaping the future of our software and building a vibrant community of innovation and collaboration. Whether you're enhancing code, reporting bugs, or suggesting new features, your contributions are invaluable.

Estamos animados em ver suas ideias ganharem vida e agradecemos seu compromisso em promover a tecnologia de detecção de objetos. Juntos, vamos continuar crescendo e inovando nesta emocionante jornada de código aberto.

Link to this sectionFAQ#

Link to this sectionPor que devo contribuir para os repositórios de código aberto da Ultralytics YOLO?#

Contribuir para os repositórios de código aberto da Ultralytics YOLO melhora o software, tornando-o mais robusto e rico em funcionalidades para toda a comunidade. As contribuições podem incluir aprimoramentos de código, correções de bugs, melhorias na documentação e implementação de novas funcionalidades. Além disso, contribuir permite que você colabore com outros desenvolvedores qualificados e especialistas na área, aprimorando suas próprias habilidades e reputação. Para detalhes sobre como começar, consulte a seção Contribuindo via Pull Requests.

Link to this sectionComo 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:

Para mais informações, consulte a seção Assinatura do CLA.

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

As docstrings no estilo Google fornecem uma documentação clara e concisa para funções e classes, melhorando a legibilidade e a manutenibilidade do código. Essas docstrings descrevem o propósito da função, argumentos e valores de retorno com regras de formatação específicas. Ao contribuir para a Ultralytics YOLO, seguir as docstrings no estilo Google garante que suas adições sejam bem documentadas e facilmente compreendidas. Para exemplos e diretrizes, visite a seção Docstrings no estilo Google.

Link to this sectionComo posso garantir que as minhas alterações passem nos testes de CI do GitHub Actions?#

Antes que o teu pull request possa ser aceite, ele deve passar em 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. Analisa a saída da CI e corrige quaisquer problemas. Para informações detalhadas sobre o processo de CI e dicas de resolução de problemas, consulta a secção GitHub Actions CI Tests.

Link to this sectionComo posso reportar um bug nos repositórios do Ultralytics YOLO?#

Para relatar um bug, forneça um Minimum Reproducible Example claro e conciso juntamente com o seu relatório de bug. Isso ajuda os desenvolvedores a identificar e corrigir o problema rapidamente. Garanta que o seu exemplo seja mínimo, porém suficiente para replicar o problema. Para passos mais detalhados sobre como relatar bugs, consulte a seção Reporting Bugs.

Link to this sectionO 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 AGPL-3.0) no teu projeto, a licença AGPL-3.0 exige que todo o teu projeto (a obra derivada) seja também 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 ao longo das suas derivadas. Se não conseguires cumprir estes requisitos, precisas de obter uma Enterprise License. Consulta a secção Open-Sourcing Your Project para detalhes.