Dicas para começar a contribuir para projetos open-source da Ultralytics

A base do software de código aberto é a colaboração, o aprendizado e o compartilhamento. Projetos de código aberto são uma ótima maneira para as pessoas se unirem para construir algo maior que elas mesmas. Na Ultralytics, levamos os princípios do código aberto a sério e sempre incentivamos você a contribuir com nossos projetos de código aberto.

Se estás com vontade de contribuir, seja através da escrita de documentação, revisão de código ou resolução de problemas, mas não tens a certeza de onde começar ou enfrentas alguns issues, estamos aqui para ajudar-te a começar. Neste artigo, vamos guiar-te por algumas dicas para começares a contribuir para os projetos open-source da Ultralytics. Vamos a isso!

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

Antes de vermos como contribuir, vamos responder à pergunta de porque é que as contribuições são tão cruciais. Acreditamos firmemente na importância das contribuições da comunidade Ultralytics. Ao participares nos nossos projetos open-source, estás a fazer muito mais do que apenas ajudar-nos a criar melhor software. Os contribuidores desempenham um papel fundamental em garantir que a nossa tecnologia permanece aberta, colaborativa e em constante evolução. As tuas contribuições mantêm os nossos projetos ativos, accessible e benéficos para utilizadores e programadores em todo o mundo!

Além de criar software de ponta, contribuir com projetos da Ultralytics é também uma oportunidade fantástica para você crescer. Você pode desenvolver suas habilidades de programação, resolução de problemas e trabalho em equipe enquanto trabalha ao lado de desenvolvedores experientes que podem oferecer orientação e compartilhar as melhores práticas. Seus esforços podem ter um impacto real em ferramentas usadas por milhares de pessoas globalmente. Engajar-se com nossa comunidade também pode te ajudar a expandir sua rede profissional, abrir novas oportunidades e aprimorar seu portfólio para se destacar perante empregadores.

Fig 1. Razões para contribuir. Imagem do autor.

Como começar com contribuições de código aberto da Ultralytics#

Um excelente ponto de partida é consultar o official Ultralytics contributing guide. Está repleto de boas práticas e dicas para aproveitares ao máximo as tuas contribuições. O primeiro passo é familiarizaste com o que já faz parte do projeto, compreendendo as contributing guidelines e explorando o código.

Quer queiras contribuir para o desenvolvimento ou apenas explorar o código mais recente, o passo seguinte é clone the Ultralytics repository. Assim que o fizeres, podes ir para o diretório do projeto e instalar o pacote em modo editável, conforme apresentado no troço de código abaixo.

Se precisares de ajuda, our quickstart guide tem tudo o que precisas para começar sem problemas.

Diferentes áreas para contribuir#

Depois de configurar seu ambiente e se familiarizar com o projeto, você pode explorar as diferentes áreas onde pode causar um impacto significativo. A Ultralytics oferece várias maneiras de se envolver, e você pode escolher como contribuir com base em suas habilidades e interesses.

Aqui está uma olhada em algumas das opções:

• Documentation: Contribuir para a documentação é uma excelente forma de mergulhar no projeto enquanto aprimoras as tuas capacidades de escrita. Podes ajudar melhorando a documentação existente, adicionando detalhes em falta ou criando novos guias que facilitem a contribuição de outros.
• Bug fixes: Se tiveres alguma experiência em programação, considera trabalhar na correção de bugs. Estes podem ir desde pequenos ajustes a problemas mais complexos, dando-te a oportunidade de causar um impacto tangível no projeto.
• Feature enhancements: Para quem está preparado para ir mais fundo, trabalhar em melhorias de funcionalidades pode ser tanto desafiante como gratificante. Isto pode envolver a adição de novas funcionalidades, a melhoria das existentes ou o trabalho no roadmap do projeto.
• Pull request reviews: A revisão de pull requests é outra forma valiosa de contribuir, especialmente se estás familiarizado com os padrões e as melhores práticas do projeto. Ao fornecer feedback e sugerir melhorias, ajudas a manter a qualidade e a integridade da base de código.
• Community discussions: Participar nas discussões da comunidade é uma excelente forma de contribuir se gostas de colaboração e de partilhar ideias. Participa nas conversas em curso, propõe novas ideias ou ajuda os outros oferecendo as tuas perspetivas e soluções.

Cada uma dessas áreas oferece uma maneira única de contribuir, e você pode escolher a que melhor se alinha com seus pontos fortes e interesses. Lembre-se, cada contribuição, não importa quão pequena, desempenha um papel fundamental em ajudar a Ultralytics a crescer e evoluir.

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

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

Ao contribuir com a documentação da Ultralytics, certifique-se de revisar a documentação existente e verificar se há problemas ou discussões que destaquem áreas que precisam de melhoria. Fazer isso ajuda a garantir que suas contribuições sejam focadas onde são mais necessárias.

Ao escrever ou editar, tenha em mente que é fundamental seguir as diretrizes do projeto para manter a consistência. Aqui estão algumas dicas de formatação:

• Usa sempre Markdown formatting.
• Comece cada documento com uma introdução clara e mantenha sua linguagem simples e acessível.
• Use marcadores para listas, texto descritivo para links e imagens com menos de 1 MB para permitir que as páginas carreguem rapidamente.
• Caso você tenha perguntas sobre formatação, uma maneira fácil de verificar novamente sua formatação é ver como a documentação anterior foi formatada.

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

Depois de fazer seu rascunho, é importante visualizá-lo criando a documentação localmente. Você pode detectar quaisquer problemas antes de enviar. Para fazer isso, comece clonando o repositório e navegando para o diretório do projeto:

Em seguida, você pode instalar as dependências necessárias:

Finalmente, sirva a documentação localmente para revisar suas alterações:

Podes ver a documentação gerada localmente navegando para http://127.0.0.1:8000/ no teu navegador web.

Após rever a clareza, precisão e consistência, podes submeter uma pull request com uma descrição clara do documento que criaste. Certifica-te de colocar o documento na secção apropriada com base no local a que pertence e onde se enquadra melhor (guides, solutions, integrations, etc.). Por favor, consulta também o ficheiro index.md para as secções relevantes e o ficheiro mkdocs.yml geral, e faz quaisquer atualizações necessárias. A atenção aos detalhes ajudará o processo de revisão a decorrer sem problemas e garantirá que a tua contribuição fica bem integrada no projeto.

Coisas para ter em mente ao contribuir com código de código aberto#

Ao fazer contribuições de código para o projeto Ultralytics, é importante seguir as melhores práticas que ajudam a garantir que seu código seja limpo, sustentável e fácil de integrar. Aqui estão alguns pontos-chave para ter em mente:

• 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: Foque 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.
• Write effective docstrings: Explica claramente o que o teu código faz e inclui links para recursos relevantes.
• Evite dependências desnecessárias: Adicione dependências apenas se elas forem absolutamente necessárias.

Fig 4. Melhores Práticas de Documentação de Código-Fonte.

Também é essencial considerar a sustentabilidade a longo prazo da base de código. Antes de fazer qualquer alteração, pergunte a si mesmo se suas modificações podem quebrar o código existente de alguém que usa a Ultralytics. Se sim, considere como abordar isso e certifique-se de que suas alterações sejam o mais compatíveis possível.

Assim que tiveres desenvolvido um pedaço de código para contribuir, precisarás de o testar. Podes usar frameworks como pytest para testar as tuas alterações antes de as submeter. A formatação consistente do código é outro aspeto da tua contribuição que é muito importante. Ferramentas como o Ruff Formatter podem ajudar-te a manter a consistência estilística e a detetar quaisquer bugs lógicos ou inconsistências no teu código.

Revisando pull requests#

Revisar pull requests (PRs) é uma ótima maneira de contribuir! Um PR é criado quando alguém solicita a mesclagem de suas alterações no projeto principal. Isso ajuda a manter o projeto Ultralytics funcionando sem problemas. Quando estiver revisando um PR, certifique-se de entender por que as alterações foram feitas. O autor deve explicar claramente o propósito e os benefícios da atualização, e você deve ver evidências de testes minuciosos em seu PR.

Fig 5. O que é uma pull request?

Vamos percorrer algumas coisas principais nas quais focar.

• Verifique se há testes unitários: Verifique se o PR inclui testes para novos recursos ou alterações para confirmar que o código funciona conforme o esperado e não introduz problemas.
• Revise as atualizações da documentação: Verifique se a documentação está atualizada para refletir as alterações ou novos recursos, incluindo exemplos, referências de 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.
• Verify CI tests: Assegura-te de que todos os testes de Continuous Integration (CI) passam, incluindo as verificações de formatação de código e os resultados dos testes unitários.
• Colabore em correções: Se algum teste falhar, trabalhe com o autor para resolver os problemas antes de aprovar o PR.

Como revisor, certifique-se de fornecer um feedback específico e claro sobre quaisquer problemas ou preocupações. Ofereça sugestões de melhoria e faça perguntas que ajudem o autor a pensar em possíveis problemas. Incentive-o a seguir as melhores práticas em programação, testes e documentação, e não hesite em indicar recursos que possam ajudar. Por último, mas não menos importante, sempre reconheça o esforço que o autor dedicou ao PR. Feedback positivo ajuda a manter uma atmosfera amigável e colaborativa na comunidade de código aberto.

Contribuir tem tudo a ver com comunidade#

Contribuir para projetos open-source como a Ultralytics pode dar-te um sentido de comunidade inspirador. Estejas a escrever código, a rever PRs, a atualizar documentação ou a participar em discussões, cada esforço ajuda o projeto a crescer e a evoluir. Responder a issues ou participar em conversas, seja no GitHub, no Discord, no Subreddit ou noutros fóruns, é uma forma valiosa de contribuir e conectar-te com os outros. Lembra-te, as tuas contribuições, por mais pequenas que sejam, têm um impacto significativo e ajudam a promover um ambiente colaborativo e de apoio para todos os envolvidos!

Na Ultralytics, somos apaixonados por impulsionar a inovação na comunidade open-source. Mantém-te a par dos nossos desenvolvimentos mais recentes visitando o nosso GitHub repository. Junta-te a our vibrant community e vê como estamos a causar impacto em setores como agriculture e manufacturing.