Contribuir para projetos de código aberto da Ultralytics
Agradecemos por considerar contribuir com nossos projetos de código aberto da Ultralytics. Sua participação 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 apresenta diretrizes claras e práticas recomendadas para ajudar você a começar.
Assista: Como contribuir para o repositório Ultralytics | Modelos, conjuntos de dados e documentação da Ultralytics 🚀
Código de Conduta#
Para garantir um ambiente acolhedor e inclusivo para todos, todos os contribuidores têm de cumprir o nosso Código de Conduta. Respeito, gentileza e profissionalismo são a base da nossa comunidade.
Contribuir por meio de pull requests#
Agradecemos muito as contribuições na forma de pull requests (PRs). Para tornar o processo de revisão o mais simples possível, segue estes passos:
- Cria um fork do repositório: começa por criar um fork do repositório pertinente da Ultralytics (por exemplo, ultralytics/ultralytics) para a tua conta do GitHub.
- Cria uma ramificação: cria uma nova ramificação no teu repositório bifurcado, com um nome claro e descritivo que reflita as tuas alterações (por exemplo,
fix-issue-123,add-feature-xyz). - Faz as tuas alterações: implementa as tuas melhorias ou correções. Garante que o teu código cumpre as diretrizes de estilo do projeto e não introduz novos erros nem avisos.
- Testa as tuas alterações: Antes de submeter, testa as tuas alterações localmente para confirmar que funcionam como esperado e não causam regressões. Os testes existentes abrangem a maioria das alterações, por isso, muitas vezes, não são necessários testes novos; quando um teste for útil, prefere algumas linhas num ficheiro de teste existente a testes com mocks.
- Faz commit das tuas alterações: faz commit das tuas alterações com mensagens 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.). - Cria um pull request: envia um pull request da tua ramificação para a ramificação
maindo repositório original da Ultralytics. Inclui um título claro e uma descrição detalhada que explique o objetivo e o âmbito das tuas alterações.
Instalação para desenvolvimento#
Clona o teu fork (ou o repositório principal) e instala-o em modo editável (-e) para que Python execute os teus ficheiros locais e detete todas as alterações sem ser necessário reinstalar:
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics
pip install -e .Para fazer com que outro projeto dependa de um fork em vez do pacote do PyPI, aponta o pip ou requirements.txt para a ramificação do fork:
git+https://github.com/YOUR_USERNAME/ultralytics.git@my-custom-branchAlterações à documentação#
O código-fonte da documentação encontra-se em docs/en/. A partir da raiz do repositório, instala as dependências de desenvolvimento e executa a validação rigorosa completa antes de abrir um PR:
uv pip install -e ".[dev]"
python docs/build_docs.pyA validação prepara referências geradas, macros e páginas de comparação antes de executar zensical build --strict. Para uma pré-visualização dinâmica mais rápida de páginas que não usam macros, executa zensical serve.
Assinatura do CLA#
Antes de podermos integrar o teu pull request, tens de assinar o nosso Acordo de Licença de Contribuidor (CLA). Este acordo legal garante que as tuas contribuições estão devidamente licenciadas, permitindo que o projeto continue a ser distribuído ao abrigo da licença AGPL-3.0.
Depois de enviares o teu pull request, o bot do CLA vai guiar-te pelo processo de assinatura. Para assinares o CLA, basta adicionares um comentário ao teu PR com o seguinte texto:
I have read the CLA Document and I sign the CLADocstrings ao estilo do Google#
Ao adicionares novas funções ou classes, inclui docstrings ao estilo do Google para uma documentação clara e padronizada. Coloca sempre os types de entrada e de saída entre parênteses (por exemplo, (bool), (np.ndarray)).
Este exemplo ilustra o formato padrão de docstrings ao estilo do Google. Repara como separa claramente a descrição da função, os argumentos, o valor devolvido e os exemplos para maximizar a legibilidade.
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 == arg2Testes de CI com GitHub Actions#
Todos os pull requests têm de passar nos testes de GitHub Actions de integração contínua (CI) antes de poderem ser integrados. Estes testes incluem análise estática, testes unitários e outras verificações para garantir que as tuas alterações cumprem os padrões de qualidade do projeto. Analisa os resultados da CI e resolve quaisquer problemas que surjam.
Boas práticas para contribuições de código#
Ao contribuíres com código para projetos da Ultralytics, tem em conta estas boas práticas:
- Evita duplicar código: reutiliza o código existente sempre que possível e minimiza os argumentos desnecessários.
- Faz alterações menores e focadas: privilegia modificações específicas em vez de alterações em grande escala.
- Simplifica sempre que possível: procura oportunidades para simplificar o código ou remover partes desnecessárias.
- Tem em conta a compatibilidade: antes de fazeres alterações, considera se estas podem quebrar 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.
Revisão de pull requests#
Rever pull requests é outra forma valiosa de contribuir. Ao rever PRs:
- Revê as atualizações da documentação: garante que a documentação foi atualizada para refletir as alterações.
- Avalia o impacto no desempenho: considera como as alterações podem afetar o desempenho.
- Verifica os testes de CI: confirma se todos os testes de integração contínua estão a passar.
- Dá feedback construtivo: apresenta comentários específicos e claros sobre quaisquer problemas ou preocupações.
- Reconhece o esforço: valoriza o trabalho do autor para manter um ambiente colaborativo positivo.
Comunicar erros#
Valorizamos muito os relatórios de erros, pois ajudam-nos a melhorar a qualidade e a fiabilidade dos nossos projetos. Ao comunicar um erro através de GitHub Issues:
- Verifica os problemas existentes: pesquisa primeiro para saber se o erro já foi comunicado.
- Fornece um Exemplo Mínimo Reproduzível: cria um pequeno trecho de código autónomo que reproduza o problema de forma consistente. Isto é essencial para depurar com eficiência.
- Descreve o ambiente: especifica o teu sistema operativo, a versão do Python, as versões das bibliotecas relevantes (por exemplo,
torch,ultralytics) e o hardware (CPU/GPU). - Explica o comportamento esperado e o comportamento real: indica claramente o que esperavas que acontecesse e o que aconteceu na realidade. Inclui quaisquer mensagens de erro ou rastreamentos de pilha.
Licença#
A Ultralytics usa a Licença Pública Geral GNU Affero v3.0 (AGPL-3.0) em seus repositórios. Essa licença promove abertura, transparência e aprimoramento colaborativo no desenvolvimento de software. Ela garante que todos os usuários tenham liberdade para usar, modificar e compartilhar o software, fomentando uma comunidade sólida de colaboração e inovação.
Incentivamos todos os contribuidores a familiarizarem-se com os termos da licença AGPL-3.0, para contribuírem de forma eficaz e ética para a comunidade de código aberto da Ultralytics.
Torna o teu projeto YOLO de código aberto ao abrigo da AGPL-3.0#
Estás a utilizar modelos ou código Ultralytics YOLO no teu projeto? A licença AGPL-3.0 exige que todo o teu trabalho derivado também seja disponibilizado como código aberto ao abrigo da AGPL-3.0. Isto garante que as modificações e os projetos maiores criados com base em fundações de código aberto permaneçam abertos.
Porque é importante cumprir a AGPL-3.0#
- Mantém o software aberto: garante que as melhorias e os trabalhos derivados beneficiam a comunidade.
- Obrigação legal: a utilização de código licenciado ao abrigo da AGPL-3.0 sujeita o teu projeto aos respetivos termos.
- Promove a colaboração: incentiva a partilha e a transparência.
Se preferires não disponibilizar o teu projeto como código aberto, considera obter uma Licença Empresarial.
Como cumprir a AGPL-3.0#
Cumprir significa disponibilizar publicamente o código-fonte completo correspondente do teu projeto ao abrigo da licença AGPL-3.0.
-
Escolhe o teu ponto de partida:
- Faz fork da Ultralytics YOLO: faz fork diretamente do repositório Ultralytics YOLO se estiveres a criar algo muito baseado nele.
- Usa o modelo da Ultralytics: começa pelo repositório de modelos da Ultralytics para obter uma estrutura organizada e modular que integre YOLO.
-
Licencia o teu projeto:
- Adiciona um ficheiro
LICENSEcom o texto integral da licença AGPL-3.0. - Adiciona um aviso no início de cada ficheiro de código-fonte a indicar a licença.
- Adiciona um ficheiro
-
Publica o teu código-fonte:
- Disponibiliza publicamente o código-fonte completo do teu projeto (por exemplo, no GitHub). Isto inclui:
- A aplicação ou o sistema completo de maior dimensão que incorpora o modelo ou o código YOLO.
- Quaisquer modificações feitas ao código original da Ultralytics YOLO.
- Scripts para treino, validação e inferência.
- Pesos do modelo, caso tenham sido modificados ou ajustados por fine-tuning.
- Ficheiros de configuração, configurações do ambiente (
requirements.txt,Dockerfiles). - Código de backend e frontend, se fizer parte de uma aplicação Web.
- Quaisquer bibliotecas de terceiros que tenhas modificado.
- Dados de treino, se forem necessários para executar/treinar novamente e puderem ser redistribuídos.
- Disponibiliza publicamente o código-fonte completo do teu projeto (por exemplo, no GitHub). Isto inclui:
-
Documenta claramente:
- Atualiza o teu
README.mdpara indicar que o projeto está licenciado ao abrigo da AGPL-3.0. - Inclui instruções claras para configurar, compilar e executar o teu projeto a partir do código-fonte.
- Atribui corretamente os créditos à Ultralytics YOLO, com uma ligação para o repositório original. Exemplo:
This project utilizes code from [Ultralytics YOLO](https://github.com/ultralytics/ultralytics), licensed under AGPL-3.0.
- Atualiza o teu
Exemplo de estrutura de repositório#
Consulta o Repositório de Modelos da Ultralytics para veres 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.ymlAo seguires estas diretrizes, garantes o cumprimento da AGPL-3.0 e apoias o ecossistema de código aberto que possibilita ferramentas poderosas como a Ultralytics YOLO.
Conclusão#
Agradecemos seu interesse em contribuir com os projetos YOLO de código aberto da Ultralytics. Sua participação ajuda a moldar nosso software e nossa comunidade, seja aprimorando o código, relatando bugs ou sugerindo novos recursos.
Agradecemos seu empenho em promover avanços na tecnologia de detecção de objetos e esperamos contar com suas contribuições.
Perguntas frequentes#
Contribuir para os repositórios YOLO de código aberto da Ultralytics melhora o software, tornando-o mais robusto e repleto de funcionalidades para toda a comunidade. As contribuições podem incluir melhorias no código, correções de erros, melhorias na documentação e implementação de novas funcionalidades. Além disso, contribuir permite-te colaborar com outros programadores e especialistas qualificados na área, desenvolvendo as tuas próprias competências e reputação. Para saberes como começar, consulta a secção Contribuir através de Pull Requests.
Para assinares o Acordo de Licença de Contribuição (CLA), segue as instruções fornecidas pelo bot do CLA depois de enviares o teu pull request. Este processo garante que as tuas contribuições são devidamente licenciadas ao abrigo da licença AGPL-3.0, preservando a integridade jurídica do projeto de código aberto. Adiciona um comentário ao teu pull request com a seguinte declaração:
I have read the CLA Document and I sign the CLAPara mais informações, consulta a secção Assinatura do CLA.
As docstrings no estilo Google fornecem documentação clara e concisa para funções e classes, melhorando a legibilidade e a facilidade de manutenção do código. Estas docstrings descrevem a finalidade da função, os argumentos e os valores devolvidos, seguindo regras de formatação específicas. Ao contribuir para a Ultralytics YOLO, seguir as docstrings no estilo Google garante que os teus acrescentos ficam bem documentados e são fáceis de compreender. Para veres exemplos e diretrizes, visita a secção Docstrings no Estilo Google.
Antes de o teu pull request poder ser integrado, tem de passar em todos os testes de Integração Contínua (CI) do GitHub Actions. Estes testes incluem análise estática, testes unitários e outras verificações para garantir que o código cumpre os padrões de qualidade do projeto. Analisa os resultados de CI e corrige quaisquer problemas. Para obteres informações detalhadas sobre o processo de CI e sugestões para resolver problemas, consulta a secção Testes de CI do GitHub Actions.
Para comunicares um erro, inclui no relatório um Exemplo Mínimo Reproduzível claro e conciso. Isto ajuda os programadores a identificar e corrigir rapidamente o problema. Garante que o teu exemplo é mínimo, mas suficiente para reproduzir o problema. Para veres instruções mais detalhadas sobre como comunicar erros, consulta a secção Comunicar erros.
Se utilizares código ou modelos Ultralytics YOLO (licenciados ao abrigo da AGPL-3.0) no teu projeto, a licença AGPL-3.0 exige que todo o teu projeto (o trabalho derivado) também seja licenciado ao abrigo da AGPL-3.0 e que o respetivo código-fonte completo seja disponibilizado publicamente. Isto garante que a natureza de código aberto do software é preservada em todos os seus derivados. Se não conseguires cumprir estes requisitos, tens de obter uma Licença Empresarial. Consulta a secção Tornar o teu projeto de código aberto para mais informações.
Comentários7
Faz uma pergunta, partilha os teus resultados ou ajuda alguém.
Mehrab-Shahbazi
Hi I will be happy if yolo add a feature that use slding window object detection. i want to add it and pull request it. is it usefull feature? will you accebt it?(if the tests passes).
Mehrab-Shahbazi
by sliding window, i mean crop big images ti smaller tiles and at the end merge all results as one output.( it is usefull for big images as you know)
Glenn JocherUltralytics@Mehrab-Shahbazi thank you for your interest in contributing! Sliding window object detection for large images can indeed be useful. If implemented efficiently and the tests pass, we welcome your pull request for review. Please ensure the feature aligns with the repository's design principles. For guidance, refer to our contributing guide.
Mehrab-Shahbazi
thank for your reply
esssyjr
Good evening all. I am trying to make a contribution for the dataset. I have forked and created a new branch but I could not see the folder specified for dataset. Should I just submit the .zip file to the root together with the read me, and send a pull request? Also, in my Github desktop I am unable to see Jupyter notebook as a code editor, but I manage to open the ultralytics cloned file in jupyter notebook, and uploaded the dataset. is that a good practice? Sorry for silly questions, I am new to open source contibution.
Glenn JocherUltralytics@esssyjr thank you for your interest in contributing! For dataset contributions, please follow the Ultralytics Contribution Guide and submit your dataset in a directory with a clear structure, including
train/andval/folders as applicable. Place the README in the same directory. Regarding Jupyter Notebook, it's fine to use it for preparing your dataset, but ensure your final submission is in the proper format per the guidelines. If you have more questions, feel free to ask on GitHub.esssyjr
Thanks for the reply, I have successfully uploaded the zip and readme file in the a folder in root of the Ultralytics repository. I requested a pull request in which it pass all the test but merge have been blocked, waiting for a approve review. Thank YOU
