Contribuindo para 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.

🤝 Código de Conduta

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

🚀 Contribuindo via Pull Requests

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

1. Faça um fork do repositório: Comece fazendo um fork do repositório da Ultralytics relevante (por exemplo, ultralytics/ultralytics) para a sua conta do GitHub.
2. Crie uma branch: Crie uma nova branch no seu repositório bifurcado com um nome claro e descritivo que reflita as suas alterações (por exemplo, fix-issue-123, add-feature-xyz).
3. Faça as suas alterações: Implemente as suas melhorias ou correções. Garanta que o seu código segue as diretrizes de estilo do projeto e não introduz novos erros ou avisos.
4. Teste as suas alterações: Antes de enviar, teste as suas alterações localmente para confirmar que funcionam conforme esperado e não causam regressões. Adicione testes se estiver a introduzir novas funcionalidades.
5. Commit your changes: Commit your changes with concise and descriptive commit messages. If your changes address a specific issue, include the issue number (e.g., 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.

📝 Assinatura do CLA

Antes de podermos mesclar o seu pull request, deve assinar o nosso Contrato de Licença de Contribuidor (CLA). Este acordo legal garante que as suas contribuições estão devidamente licenciadas, permitindo que o projeto continue a ser distribuído sob a licença AGPL-3.0.

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

✍️ Docstrings no estilo Google

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

✅ 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.

✨ Melhores práticas para contribuições de código

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

• Evite a duplicação de código: Reutilize 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 alterações 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 estas podem quebrar código existente que utiliza Ultralytics.
• Use formatação consistente: Ferramentas como o Ruff Formatter podem ajudar a manter a consistência estilística.
• Adicione testes apropriados: Inclua testes para novas funcionalidades para garantir que funcionam como esperado.

👀 Revisando Pull Requests

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

• Verifique a existência de testes unitários: Confirme que o PR inclui testes para novas funcionalidades ou alterações.
• Revise as atualizações na documentação: Garanta que a documentação está atualizada para refletir as alterações.
• Avalie o impacto no desempenho: Considere como as alterações podem afetar o desempenho.
• Verifique os testes de CI: Confirme que todos os testes de Integração Contínua estão passando.
• 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.

🐞 Reportando bugs

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

• Verifique problemas existentes: Pesquise primeiro para ver se o bug já foi reportado.
• Forneça um Exemplo Mínimo Reproduzível: Crie um pequeno trecho de código autônomo que reproduza consistentemente o problema. Isto é crucial para uma depuração eficiente.
• Descreva o ambiente: Especifique o seu sistema operacional, versão do Python, versões relevantes de bibliotecas (por exemplo, torch, ultralytics) e hardware (CPU/GPU).
• Explique o comportamento esperado vs. real: Afirme claramente o que 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 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 familiarizarem-se com os termos da licença AGPL-3.0 para contribuir de forma eficaz e ética para a comunidade de código aberto da Ultralytics.

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

Está a usar modelos ou código YOLO da Ultralytics no 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 as modificações e projetos maiores construídos sobre bases de código aberto 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: O uso de código licenciado sob AGPL-3.0 vincula o seu projeto aos seus termos.
• Promove a colaboração: Encoraja a partilha e a transparência.

Se preferir não tornar o seu projeto de código aberto, considere obter uma Licença Empresarial.

Como cumprir a AGPL-3.0

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

1. Escolha o seu ponto de partida:

   • Fork do YOLO da Ultralytics: Faça um fork direto do repositório YOLO da Ultralytics caso esteja construindo algo muito próximo dele.
   • Use o modelo da Ultralytics: Comece com o repositório de modelo da Ultralytics para uma configuração limpa e modular integrando o YOLO.

2. Licencie o seu projeto:

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

3. Publique o seu código-fonte:

   • Torne o código-fonte do seu projeto inteiro publicamente acessível (por exemplo, no GitHub). Isto inclui:
     • A aplicação ou sistema maior completo que incorpora o modelo ou código YOLO.
     • Quaisquer modificações feitas ao código original do YOLO da Ultralytics.
     • Scripts para treinamento, validação e inferência.
     • Pesos do modelo se modificados ou ajustados.
     • Ficheiros de configuração, configurações de ambiente (requirements.txt, Dockerfiles).
     • Código de backend e frontend se for parte de uma aplicação web.
     • Quaisquer bibliotecas de terceiros que você tenha modificado.
     • Dados de treinamento se forem necessários para rodar/retreinar e se puderem ser redistribuídos.

4. Documente claramente:

   • Atualize o seu README.md para afirmar que o projeto está licenciado sob a AGPL-3.0.
   • Inclua instruções claras sobre como configurar, construir e executar o seu projeto a partir do código-fonte.
   • Atribua os créditos ao YOLO da Ultralytics apropriadamente, vinculando ao 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

Consulte o Repositório de Modelo da Ultralytics para 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 seguir estas diretrizes, você garante conformidade com a AGPL-3.0, apoiando o ecossistema de código aberto que permite ferramentas poderosas como o YOLO da Ultralytics.

Conclusã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 empolgados para ver as suas ideias ganharem vida e agradecemos o seu compromisso em avançar a tecnologia de detecção de objetos. Juntos, vamos continuar a crescer e inovar nesta emocionante jornada de código aberto.

FAQ

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

Contributing to Ultralytics YOLO open-source repositories improves the software, making it more robust and feature-rich for the entire community. Contributions can include code enhancements, bug fixes, documentation improvements, and new feature implementations. Additionally, contributing allows you to collaborate with other skilled developers and experts in the field, enhancing your own skills and reputation. For details on how to get started, refer to the Contributing via Pull Requests section.

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

Para assinar o Contrato de Licença de Contribuidor (CLA), siga as instruções fornecidas pelo bot do CLA após enviar o seu pull request. Este processo garante que as suas contribuições estão 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, veja a seção Assinatura do CLA.

O que são docstrings estilo Google e por que são necessárias para contribuições ao YOLO da Ultralytics?

Docstrings estilo Google fornecem documentação clara e concisa para funções e classes, melhorando a legibilidade e 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 YOLO da Ultralytics, seguir as docstrings estilo Google garante que as suas adições estão bem documentadas e facilmente compreendidas. Para exemplos e diretrizes, visite a seção Docstrings estilo Google.

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

Antes de o teu pull request poder ser fundido (merged), este 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. Analisa o resultado do 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.

Como relato um bug nos repositórios do Ultralytics YOLO?

Para relatar um bug, fornece um Exemplo Mínimo Reproduzível claro e conciso juntamente com o teu relatório de bug. Isto ajuda os programadores a identificar e corrigir o problema rapidamente. Garante que o teu exemplo é mínimo, mas suficiente para replicar o problema. Para passos mais detalhados sobre como relatar 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 AGPL-3.0) no teu projeto, a licença AGPL-3.0 exige que todo o teu projeto (a obra derivada) também deve ser licenciado sob a AGPL-3.0 e o seu código-fonte completo deve ser disponibilizado publicamente. Isto garante que a natureza open-source do software seja preservada ao longo das suas derivações. Se não conseguires cumprir estes requisitos, precisas de obter uma Licença Empresarial. Consulta a secção Open-Sourcing Your Project para detalhes.