Contribuindo para Projetos de Código Aberto da Ultralytics

Bem-vindo! Estamos muito felizes por você estar considerando contribuir para nossos projetos Ultralytics de código aberto. Seu envolvimento não apenas ajuda a melhorar a qualidade de nossos repositórios, mas também beneficia toda a comunidade de visão computacional. Este guia fornece diretrizes claras e práticas recomendadas para ajudá-lo a começar.

Assista: Como Contribuir para o Repositório Ultralytics | Modelos, Conjuntos de Dados e Documentação Ultralytics 🚀

🤝 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 tranquilo possível, siga estas etapas:

1. Faça um fork do repositório: Comece fazendo um fork do repositório Ultralytics relevante (por exemplo, ultralytics/ultralytics) para 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 suas alterações: Implemente suas melhorias ou correções. Certifique-se de que seu código esteja em conformidade com 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 se elas funcionam como esperado e não causam regressões. Adicione testes se você estiver introduzindo novas funcionalidades.
5. Commit suas alterações: Faça commit de 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 do seu branch para o main branch do repositório Ultralytics original. Forneça um título claro e uma descrição detalhada explicando o propósito e o escopo de suas alterações.

📝 Assinatura do CLA

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

Após enviar sua solicitação pull, o bot CLA irá guiá-lo através do processo de assinatura. Para assinar o CLA, basta adicionar um comentário em 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, inclua Docstrings no estilo Google para documentação clara e padronizada. Sempre inclua a entrada e 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

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

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

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

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

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

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

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Returns:
   (np.ndarray): Predicted masks with shape HxWxN.
   (list): Confidence scores for each instance.

Returns:
   (tuple): Tuple containing:
       - (np.ndarray): Predicted masks with shape HxWxN.
       - (list): Confidence scores for each instance.

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

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

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

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    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 serem mesclados. Esses testes incluem linting, testes de unidade e outras verificações para garantir que suas alterações atendam aos padrões de qualidade do projeto. Revise a saída do CI e resolva quaisquer problemas que surjam.

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

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

• Evite 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 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 elas podem quebrar o código existente que usa 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 novos recursos para garantir que funcionem como esperado.

👀 Revisando Pull Requests

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

• Verificar testes unitários: Verifique se o PR inclui testes para novos recursos ou alterações.
• Revisar atualizações da documentação: Garantir que a documentação seja atualizada para refletir as mudanças.
• Avaliar o impacto no desempenho: Considere como as alterações podem afetar o desempenho.
• Verificar testes de CI: Confirme se 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.
• Reconhecer 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 eles nos ajudam a melhorar a qualidade e a confiabilidade de nossos projetos. Ao relatar um bug através de Problemas do GitHub:

• Verificar problemas existentes: Pesquise primeiro para ver se o bug já foi reportado.
• Forneça um Exemplo Mínimo e Reproduzível: Crie um pequeno trecho de código autocontido que reproduza consistentemente o problema. Isto é crucial para uma depuração eficiente.
• Descreva o ambiente: Especifique seu sistema operacional, versão do Python, versões de biblioteca relevantes (por exemplo, torch, ultralytics), e hardware (CPU/GPU).
• Explique o comportamento esperado vs. o comportamento real: Indique claramente o que esperava que acontecesse e o que realmente ocorreu. Inclua quaisquer mensagens de erro ou "tracebacks".

📜 Licença

A Ultralytics usa a GNU Affero General Public License v3.0 (AGPL-3.0) para seus repositórios. Esta licença promove abertura, transparência e melhoria colaborativa no desenvolvimento de software. 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.

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

🌍 Tornando Seu Projeto YOLO de Código Aberto Sob AGPL-3.0

Está usando modelos ou código Ultralytics YOLO no seu projeto? A licença AGPL-3.0 exige que todo o seu trabalho derivado também seja de código aberto sob AGPL-3.0. Isso garante que as modificações e os 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 as melhorias e os trabalhos derivados beneficiem a comunidade.
• Requisito Legal: Usar código licenciado sob AGPL-3.0 vincula seu projeto aos seus termos.
• Promove a Colaboração: Incentiva o compartilhamento e a transparência.

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

Como Cumprir com a AGPL-3.0

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

1. Escolha o Seu Ponto de Partida:

   • Fork do Ultralytics YOLO: Faça um fork diretamente do repositório Ultralytics YOLO se estiver construindo algo intimamente relacionado a ele.
   • Use o Template Ultralytics: Comece com o repositório de template Ultralytics para uma configuração limpa e modular que integra o YOLO.

2. Licencie Seu Projeto:

   • Adicione um LICENSE ficheiro contendo o texto completo do Licença AGPL-3.0.
   • Adicione um aviso no topo de cada arquivo de origem indicando a licença.

3. Publique o Seu Código Fonte:

   • Faça seu código-fonte de todo o projeto acessível publicamente (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 Ultralytics YOLO original.
     • Scripts para treinamento, validação e inferência.
     • Pesos do modelo se forem modificados ou ajustados.
     • Arquivos de Configuração, 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ário para executar/retreinar e redistribuíveis.

4. Documente Claramente:

   • Atualize seu README.md para declarar que o projeto está licenciado sob AGPL-3.0.
   • Inclua instruções claras sobre como configurar, construir e executar seu projeto a partir do código-fonte.
   • Atribua Ultralytics YOLO apropriadamente, vinculando de volta 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 Modelos da Ultralytics para obter 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 a conformidade com a AGPL-3.0, apoiando o ecossistema de código aberto que possibilita ferramentas poderosas como o Ultralytics YOLO.

🎉 Conclusão

Agradecemos o seu interesse em contribuir para os projetos YOLO de código aberto da Ultralytics. Sua participação é essencial para moldar o futuro do nosso software e construir uma comunidade vibrante de inovação e colaboração. Seja aprimorando o código, relatando bugs ou sugerindo novos recursos, suas contribuições são inestimáveis.

Estamos entusiasmados para ver as suas ideias a ganharem vida e agradecemos o seu compromisso em fazer avançar a tecnologia de deteção de objetos. Juntos, vamos continuar a crescer e a inovar nesta emocionante jornada de código aberto. Boa programação! 🚀🌟

FAQ

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

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

Como assinar o Contrato de Licença do Colaborador (CLA) para Ultralytics YOLO?

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

I have read the CLA Document and I sign the CLA

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

O que são docstrings no estilo Google e por que são obrigatórias para contribuições do Ultralytics YOLO?

Docstrings no estilo Google fornecem documentação clara e concisa para funções e classes, melhorando a legibilidade e a manutenção do código. Essas docstrings descrevem o propósito, os argumentos e os valores de retorno da função com regras de formatação específicas. Ao contribuir para o 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.

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

Antes que seu pull request possa ser mesclado, ele deve passar em todos os testes de Integração Contínua (CI) do GitHub Actions. Esses testes incluem linting, testes de unidade e outras verificações para garantir que o código atenda aos padrões de qualidade do projeto. Revise a saída do CI e corrija quaisquer problemas. Para obter informações detalhadas sobre o processo de CI e dicas de solução de problemas, consulte a seção Testes de CI do GitHub Actions.

Como reportar um bug nos repositórios Ultralytics YOLO?

Para reportar um bug, forneça um Exemplo Mínimo Reproduzível claro e conciso junto com seu relatório de bug. Isso ajuda os desenvolvedores a identificar e corrigir o problema rapidamente. Certifique-se de que seu exemplo seja mínimo, mas suficiente para replicar o problema. Para obter etapas mais detalhadas sobre como reportar bugs, consulte a seção Reportando Bugs.

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

Se você usar código ou modelos Ultralytics YOLO (licenciados sob AGPL-3.0) em seu projeto, a licença AGPL-3.0 exige que todo o seu projeto (o trabalho derivado) também seja licenciado sob AGPL-3.0 e que seu código-fonte completo seja disponibilizado publicamente. Isso garante que a natureza de código aberto do software seja preservada em todos os seus derivados. Se você não puder atender a esses requisitos, precisará obter uma Licença Enterprise. Consulte a seção Open-Sourcing Your Project para obter detalhes.

📅 Criado há 1 ano ✏️ Atualizado há 2 meses

Comentários