Contribuir para Ultralytics Projectos de código aberto

Bem-vindo! Estamos muito contentes por estar a considerar contribuir para o nosso Ultralytics projectos de código aberto. O seu envolvimento 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 fornece diretrizes claras e práticas recomendadas para ajudá-lo a começar.

Ver: 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 colaboradores devem aderir ao nosso Código de Conduta. O respeito, a gentileza e o profissionalismo estão no centro da nossa comunidade.

🚀 Contribuir através de Pull Requests

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

1. Bifurcar o repositório: Comece por bifurcar o repositório Ultralytics relevante (por exemplo, ultralytics) na sua conta GitHub.
2. Criar um ramo: Crie um novo ramo no seu repositório bifurcado com um nome claro e descritivo que reflicta as suas alterações (por exemplo, fix-issue-123, add-feature-xyz).
3. Faça as suas alterações: Implemente as suas melhorias ou correcções. Certifique-se de que o seu código cumpre as diretrizes de estilo do projeto e não introduz novos erros ou avisos.
4. Teste as suas alterações: Antes de submeter, teste as suas alterações localmente para confirmar que funcionam como esperado e não causam regressões. Adicione testes se estiver a introduzir novas funcionalidades.
5. Confirmar as alterações: Confirme as suas alterações com mensagens de confirmação concisas e descritivas. Se as suas alterações se referem a um problema específico, inclua o número do problema (por exemplo, Fix #123: Corrected calculation error.).
6. Criar um pull request: Envie um pull request do seu branch para o main do repositório original do Ultralytics . Forneça um título claro e uma descrição detalhada que explique o objetivo e o âmbito das suas alterações.

Assinatura CLA

Antes de podermos fazer o merge do seu pull request, tem de assinar o nosso Contributor License Agreement (CLA). Este acordo legal assegura que as suas contribuições estão devidamente licenciadas, permitindo que o projeto continue a ser distribuído sob a licençaAGPL-3.0 .

Depois de submeter o seu pull request, o bot CLA irá guiá-lo através do 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 Google

Ao adicionar novas funções ou classes, inclua Docstrings Google para uma documentação clara e normalizada. Inclua sempre 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 Integração Contínua (CI) do GitHub Actions antes de serem mesclados. Estes testes incluem linting, testes unitários e outras verificações para garantir que as suas alterações cumprem os padrões de qualidade do projeto. Revise a saída de CI e resolva quaisquer problemas que surjam.

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

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

• Evitar a duplicação de código: Reutilizar o código existente sempre que possível e minimizar os argumentos desnecessários.
• Fazer alterações mais pequenas e específicas: Concentre-se em modificações específicas em vez de alterações em grande escala.
• Simplificar quando possível: Procurar oportunidades para simplificar o código ou remover partes desnecessárias.
• Considere a compatibilidade: Antes de efetuar alterações, considere se estas podem quebrar o código existente que utiliza Ultralytics.
• Utilize uma formatação consistente: Ferramentas como o Ruff Formatter podem ajudar a manter a consistência estilística.
• Adicionar testes apropriados: Incluir testes para as novas funcionalidades para garantir que funcionam como esperado.

👀 Revisão de pedidos pull

A revisão de pull requests é outra forma valiosa de contribuir. Ao revisar PRs:

• Verificar a existência de testes unitários: Verificar se o PR inclui testes para novas funcionalidades ou alterações.
• Rever as actualizações da documentação: Assegurar que a documentação é actualizada para refletir as alterações.
• Avaliar o impacto no desempenho: Considerar como as alterações podem afetar o desempenho.
• Verificar testes de CI: Confirmar que todos os testes de Integração Contínua estão a ser aprovados.
• Fornecer feedback construtivo: Dê feedback específico e claro sobre quaisquer questões ou preocupações.
• Reconhecer o esforço: Reconhecer o trabalho do autor para manter um ambiente de colaboração positivo.

🐞 Comunicar erros

Valorizamos muito os relatórios de erros, pois ajudam-nos a melhorar a qualidade e a fiabilidade dos nossos projectos. Ao relatar um bug via GitHub Issues:

• Verificar problemas existentes: Pesquise primeiro para ver se o erro já foi comunicado.
• Forneça um exemplo mínimo reproduzível: Crie um trecho de código pequeno e independente que reproduza o problema de forma consistente. Isto é crucial para uma depuração eficiente.
• Descrever o ambiente: Especifique o seu sistema operativo, a versão Python , as versões das bibliotecas relevantes (por exemplo, torch, ultralytics), e hardware (CPU/GPU).
• Explicar o comportamento esperado versus o comportamento real: Indique claramente o que esperava que acontecesse e o que efetivamente ocorreu. Inclua quaisquer mensagens de erro ou rastreios.

📜 Licenç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, a transparência e a melhoria colaborativa no desenvolvimento de software. Assegura que todos os utilizadores têm a liberdade de utilizar, modificar e partilhar o software, fomentando uma forte comunidade de colaboração e inovação.

Encorajamos todos os colaboradores a familiarizarem-se com os termos da licençaAGPL-3.0 para contribuírem eficaz e eticamente para a comunidade de código aberto Ultralytics .

🌍 Abrir o seu projeto YOLO sob a AGPL-3.0

Está a utilizar modelos ou códigoYOLO Ultralytics no seu projeto? A licençaAGPL-3.0 exige que todo o seu trabalho derivado também seja de código aberto sob a AGPL-3.0. Isto garante que as modificações e os projectos maiores construídos sobre bases de código aberto permaneçam abertos.

Por que a conformidade com AGPL-3.0 é importante

• Mantém o software aberto: Assegura que as melhorias e os trabalhos derivados beneficiam a comunidade.
• Requisito legal: A utilização de código licenciado AGPL-3.0 vincula o seu projeto aos seus termos.
• Promove a colaboração: Incentiva a partilha e a transparência.

Se preferir não abrir o código do seu projeto, considere obter uma Licença Empresarial.

Como cumprir a AGPL-3.0

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

1. Escolha o seu ponto de partida:

   • Bifurcar o Ultralytics YOLO: Bifurcar diretamente o repositórioUltralytics YOLO se estiver a construir com base nele.
   • Utilizar o modelo Ultralytics : Comece com o repositório de modelos doUltralytics para obter uma configuração limpa e modular que integre YOLO.

2. Licenciar o seu projeto:

   • Adicionar um LICENSE ficheiro que contém o texto completo do Licença AGPL-3.0.
   • Adicionar um aviso no topo de cada ficheiro fonte indicando a licença.

3. Publique seu código-fonte:

   • Faça o seu todo o código fonte do projeto publicamente acessíveis (por exemplo, no GitHub). Isto inclui:
     • A aplicação ou sistema completo de maior dimensão que incorpora o modelo ou código YOLO .
     • Quaisquer modificações efectuadas ao código original Ultralytics YOLO .
     • Scripts para formação, 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 fizer parte de uma aplicação Web.
     • Quaisquer bibliotecas de terceiros que tenha modificado.
     • Dados de treino, se necessário para executar/reformular e redistribuíveis.

4. Documento claro:

   • Atualizar o seu README.md para indicar 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.
   • Atribuir o Ultralytics YOLO de forma adequada, ligando-o 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 modelosUltralytics 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, garante a conformidade com a AGPL-3.0, apoiando o ecossistema de código aberto que permite ferramentas poderosas como o Ultralytics YOLO.

🎉 Conclusão

Obrigado pelo seu interesse em contribuir para os projectos Ultralytics projectos de código aberto YOLO . A sua participação é essencial para moldar o futuro do nosso software e construir uma comunidade vibrante de inovação e colaboração. Quer esteja a melhorar o código, a comunicar erros ou a sugerir novas funcionalidades, as suas contribuições são inestimáveis.

Estamos entusiasmados por ver as suas ideias ganharem vida e apreciamos o seu empenho no avanço da tecnologia de deteção de objectos. Juntos, vamos continuar a crescer e a inovar nesta excitante viagem de código aberto. Boa programação! 🚀🌟

FAQ

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

A contribuição para os repositórios de código aberto Ultralytics YOLO melhora o software, tornando-o mais robusto e rico em funcionalidades para toda a comunidade. As contribuições podem incluir melhorias no código, correcções de erros, melhorias na documentação e implementações de novas funcionalidades. Além disso, a contribuição permite-lhe colaborar com outros programadores qualificados e especialistas na área, melhorando as suas próprias competências e reputação. Para obter detalhes sobre como começar, consulte a secção Contribuir através de Pull Requests.

Como é que assino o Contrato de Licença do Contribuinte (CLA) para Ultralytics YOLO ?

Para assinar o Contrato de Licença do Contribuinte (CLA), siga as instruções fornecidas pelo bot do CLA depois de submeter o seu pull request. Este processo garante que as suas contribuições são devidamente licenciadas ao abrigo da 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, consulte a secção Assinatura CLA.

O que são docstrings ao estilo de Google e porque é que são necessárias para as contribuições Ultralytics YOLO ?

GoogleAs docstrings de estilo -style fornecem documentação clara e concisa para funções e classes, melhorando a legibilidade e a manutenção do código. Estas docstrings descrevem o objetivo da função, os argumentos e os valores de retorno com regras de formatação específicas. Ao contribuir para Ultralytics YOLO , seguir Google-style docstrings garante que suas adições sejam bem documentadas e facilmente compreendidas. Para exemplos e orientações, visite a secção Google-Style Docstrings.

Como posso garantir que as minhas alterações passam nos testes de CI de 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 de 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 é que comunico um erro nos repositórios Ultralytics YOLO ?

Para comunicar um erro, forneça um Exemplo Mínimo Reprodutível claro e conciso juntamente com o seu relatório de erro. Isto ajuda os programadores a identificar e corrigir rapidamente o problema. Certifique-se de que o seu exemplo é mínimo, mas suficiente para reproduzir o problema. Para obter passos mais detalhados sobre como comunicar erros, consulte a secção Comunicar erros.

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

Se utilizar o código ou os modelos Ultralytics YOLO (licenciados sob a AGPL-3.0) no seu projeto, a licença AGPL-3.0 exige que todo o seu projeto (o trabalho derivado) também seja licenciado sob a AGPL-3.0 e que o seu código-fonte completo seja disponibilizado ao público. Isto assegura que a natureza de código aberto do software é preservada em todos os seus derivados. Se não conseguir cumprir estes requisitos, terá de obter uma Licença Empresarial. Consulte a secção Open-Sourcing Your Project para obter mais informações.

📅C riado há 1 ano ✏️ Atualizado há 22 dias

Comentários