Dicas para começar a contribuir com os projetos de código aberto da Ultralytics

A colaboração, a aprendizagem e a partilha são a base do software de código aberto. Os projetos de código aberto são uma ótima forma de as pessoas se juntarem para criar algo maior do que cada uma delas. Na Ultralytics, valorizamos profundamente os princípios do código aberto e incentivamos-te sempre a contribuir para os nossos projetos de código aberto.

Se você quer contribuir, seja escrevendo documentação, revisando código ou resolvendo problemas, mas não sabe por onde começar ou está enfrentando dificuldades, estamos aqui para ajudar você a dar os primeiros passos. Neste artigo, apresentaremos algumas dicas para começar a contribuir com os projetos de código aberto da Ultralytics.

A importância das contribuições da comunidade Ultralytics#

Antes de vermos como contribuir, vamos responder à pergunta de por que as contribuições são tão importantes. Acreditamos firmemente na importância das contribuições da comunidade Ultralytics. Ao participar de nossos projetos de código aberto, você faz mais do que simplesmente nos ajudar a criar software melhor. Os colaboradores desempenham um papel fundamental para garantir que nossa tecnologia continue aberta, colaborativa e em constante evolução. Suas contribuições mantêm nossos projetos ativos, acessíveis e úteis para usuários e desenvolvedores do mundo todo!

Além de criar software, contribuir com os projetos da Ultralytics também é uma excelente oportunidade para você crescer. Você pode desenvolver suas habilidades de programação, resolução de problemas e trabalho em equipe ao lado de desenvolvedores experientes, que podem oferecer orientação e compartilhar boas práticas. Seu trabalho pode ter um impacto real em ferramentas usadas por milhares de pessoas no mundo todo. O envolvimento com nossa comunidade também pode ajudar você a ampliar sua rede profissional, abrir novas oportunidades e aprimorar seu portfólio para se destacar perante empregadores.

Fig. 1. Motivos para contribuir. Imagem do autor.

Como começar a contribuir para projetos de código aberto da Ultralytics#

Um ótimo ponto de partida é consultar o guia oficial de contribuição da Ultralytics. Ele reúne boas práticas e dicas para ajudar você a aproveitar ao máximo suas contribuições. O primeiro passo é se familiarizar com o que já faz parte do projeto, entendendo as diretrizes de contribuição, assinando o Acordo de Licença do Colaborador (CLA) e explorando o código.

Quer pretendas contribuir para o desenvolvimento ou apenas explorar o código mais recente, o passo seguinte é clonar o repositório da Ultralytics. Depois, podes aceder ao diretório do projeto e instalar o pacote em modo editável, como mostra o excerto de código abaixo.

git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics
pip install -e .

Se precisares de ajuda, o nosso guia de início rápido tem tudo o que precisas para começar sem dificuldades.

Diferentes áreas para contribuir#

Depois de configurares o teu ambiente e te familiarizares com o projeto, podes explorar as diferentes áreas em que podes causar um impacto significativo. A Ultralytics oferece várias formas de participar, e podes escolher como contribuir com base nas tuas competências e interesses.

Aqui estão algumas opções:

• Documentação: contribuir para a documentação é uma ótima forma de te familiarizares com o projeto enquanto aperfeiçoas as tuas competências de escrita. Podes ajudar a melhorar a documentação existente, acrescentar informações em falta ou criar novos guias que facilitem a contribuição de outras pessoas.
• Correções de erros: se tens alguma experiência de programação, considera trabalhar na correção de erros. Estes podem ir de pequenos ajustes a problemas mais complexos, dando-te a oportunidade de ter um impacto concreto no projeto.
• Melhorias de funcionalidades: Para quem está pronto para aprofundar-se, trabalhar em melhorias de funcionalidades pode ser desafiador e gratificante. Isso pode envolver adicionar funcionalidades novas, aprimorar as existentes ou trabalhar no roteiro do projeto.
• Análises de pull requests: Analisar pull requests é outra forma valiosa de contribuir, especialmente se você conhece os padrões e as práticas recomendadas do projeto. Ao dar feedback e sugerir melhorias, você ajuda a manter a qualidade e a integridade da base de código.
• Discussões da comunidade: Participar das discussões da comunidade é uma excelente forma de contribuir se você gosta de colaborar e compartilhar ideias. Participe das conversas em andamento, proponha ideias novas ou ajude outras pessoas compartilhando suas percepções e soluções.

Cada uma dessas áreas oferece uma forma única de contribuir, e você pode escolher aquela que melhor se alinha aos seus pontos fortes e interesses. Lembre-se: toda contribuição, por menor que seja, desempenha um papel fundamental para ajudar a Ultralytics a crescer e evoluir.

Fig. 2. Toda contribuição é valorizada em nossa comunidade em crescimento. Fonte da imagem: Envato Elements.

Contribuir para a documentação de código aberto da Ultralytics#

Ao contribuir para a documentação da Ultralytics, revise a documentação existente e procure problemas ou discussões que indiquem áreas que precisam de melhorias. Isso ajuda a garantir que suas contribuições se concentrem no que é mais necessário.

Ao escrever ou editar, lembre-se de que é fundamental seguir as diretrizes do projeto para manter a consistência. Confira algumas dicas de formatação:

• Use sempre a formatação Markdown.
• Comece cada documento com uma introdução clara e use uma linguagem simples e acessível.
• Use listas com marcadores, textos descritivos para links e imagens com menos de 1 MB para que as páginas carreguem rapidamente.
• Se tiver dúvidas sobre formatação, uma maneira fácil de conferir a sua formatação é verificar como a documentação anterior foi formatada.

Fig. 3. Um exemplo de formatação Markdown (à esquerda) e do documento final renderizado (à direita). Imagem do autor.

Depois de preparar o rascunho, é importante visualizá-lo compilando a documentação localmente. Assim, você pode detectar problemas antes de enviar. Para isso, comece clonando o repositório e acessando o diretório do projeto:

git clone https://github.com/ultralytics/ultralytics.git
cd ultralytics

Em seguida, instale as dependências necessárias:

pip install -e ".[dev]"

Por fim, compile a documentação e disponibilize-a localmente para revisar suas alterações:

python docs/build_docs.py
python -m http.server --directory site

Você pode visualizar a documentação compilada localmente acessando http://127.0.0.1:8000/ no navegador.

Depois de revisar a clareza, a precisão e a consistência, você pode enviar um pull request com uma descrição clara do documento que criou. Coloque o documento na seção apropriada, de acordo com o local a que pertence e onde melhor se encaixa (guias, soluções, integrações etc.). Consulte também o arquivo index.md para ver as seções relevantes e o arquivo mkdocs.yml geral, e faça as atualizações necessárias. Atenção aos detalhes ajudará a agilizar o processo de revisão e garantirá que sua contribuição seja bem integrada ao projeto.

O que você deve ter em mente ao contribuir com código de código aberto#

Ao contribuir com código para o projeto Ultralytics, é importante seguir as boas práticas que ajudam a garantir que seu código seja limpo, fácil de manter e simples de integrar. Confira alguns pontos importantes:

• Evite duplicar 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 alterações menores e direcionadas, em vez de grandes modificações.
• Simplifique ou remova código: Procure oportunidades para simplificar o código ou remover partes desnecessárias.
• Escreva docstrings eficazes: Explique claramente o que seu código faz e inclua links para recursos relevantes.
• Evite dependências desnecessárias: Só adicione dependências se forem absolutamente necessárias.

Fig. 4. Práticas recomendadas para documentação de código-fonte.

Também é essencial considerar a sustentabilidade da base de código a longo prazo. Antes de fazer qualquer alteração, pergunte a si mesmo se suas modificações podem interromper o código existente de alguém que usa a Ultralytics. Se esse for o caso, pense em como resolver isso e garanta que suas alterações sejam o mais compatíveis possível.

Depois de desenvolver um trecho de código para contribuir, você precisará testá-lo. Você pode usar frameworks como pytest para testar suas alterações antes de enviá-las. A formatação consistente do código é outro aspecto muito importante da sua contribuição. Ferramentas como Ruff podem ajudar a manter a consistência de estilo e detectar erros ou inconsistências comuns no código.

Análise de pull requests#

Analisar pull requests (PRs) é uma ótima forma de contribuir! Um PR é criado quando alguém solicita a integração de suas alterações ao projeto principal. Isso ajuda a manter o projeto Ultralytics funcionando sem problemas. Ao analisar um PR, procure entender por que as alterações foram feitas. O autor deve explicar claramente o objetivo e os benefícios da atualização, e você deve encontrar evidências de testes completos no PR.

Fig. 5. O que é um pull request?

Vamos analisar alguns pontos importantes.

• Verifique os testes unitários: Confira se o PR inclui testes para novas funcionalidades ou alterações, a fim de confirmar que o código funciona como esperado e não introduz problemas.
• Revise as atualizações da documentação: Verifique se a documentação foi atualizada para refletir alterações ou novas funcionalidades, incluindo exemplos, referências da API e outros detalhes relevantes.
• Avalie o impacto no desempenho: Considere como as alterações afetam o desempenho. Se necessário, solicite benchmarks de desempenho ou testes adicionais.
• Verifique os testes de CI: Garanta que todos os testes de integração contínua (CI) estejam passando, incluindo as verificações de formatação do código e os resultados dos testes unitários.
• Colabore na correção de problemas: Se algum teste falhar, trabalhe com o autor para resolver os problemas antes de aprovar o PR.

Como revisor, procure dar feedback específico e claro sobre quaisquer problemas ou preocupações. Sugira melhorias e faça perguntas que ajudem o autor a pensar em possíveis problemas. Incentive o autor a seguir as boas práticas de programação, testes e documentação, e não hesite em indicar recursos que possam ajudar. Por último, mas não menos importante, reconheça sempre o esforço do autor no PR. O feedback positivo ajuda a manter um ambiente amigável e colaborativo na comunidade de código aberto.

Contribuir é, acima de tudo, participar da comunidade#

Contribuir com projetos de código aberto como os da Ultralytics pode proporcionar uma inspiradora sensação de comunidade. Seja escrevendo código, revisando PRs, atualizando a documentação ou participando de discussões, todo esforço ajuda o projeto a crescer e evoluir. Responder a questões ou participar de conversas no GitHub, no Discord, no Reddit ou em outros fóruns é uma maneira valiosa de contribuir e se conectar com outras pessoas. Lembre-se: suas contribuições, por menores que sejam, têm um impacto significativo e ajudam a promover um ambiente colaborativo e acolhedor para todos!

Na Ultralytics, somos apaixonados por impulsionar a inovação na comunidade de código aberto. Acompanhe nossas novidades visitando nosso repositório no GitHub. Participe da nossa comunidade vibrante e veja como estamos causando impacto em setores como agricultura e manufatura.