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

A base do software open source é a colaboração, a aprendizagem e a partilha. Os projetos open source são uma excelente forma de as pessoas se unirem para criar algo maior do que elas próprias. Na Ultralytics, valorizamos profundamente os princípios do open source e incentivamos-te sempre a contribuir para os nossos projetos open source.

Se estás entusiasmado por contribuir, seja escrevendo documentação, revendo código ou resolvendo problemas, mas não sabes por onde começar ou estás a enfrentar alguns problemas, estamos aqui para te ajudar a começar. Neste artigo, vamos apresentar algumas dicas para começares a contribuir para os projetos open source da Ultralytics. Vamos começar!

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

Antes de vermos como contribuir, vamos responder à pergunta sobre por que motivo as contribuições são tão importantes. Acreditamos firmemente na importância das contribuições da comunidade da Ultralytics. Ao participares nos nossos projetos open source, estás a fazer mais do que simplesmente ajudar-nos a criar software melhor. Os contribuidores desempenham um papel fundamental para garantir que a nossa tecnologia continua aberta, colaborativa e em constante evolução. As tuas contribuições mantêm os nossos projetos ativos, acessíveis e úteis para utilizadores e programadores de todo o mundo!

Além de criares software de ponta, contribuir para os projetos da Ultralytics é também uma excelente oportunidade para cresceres. Podes desenvolver as tuas competências de programação, resolução de problemas e trabalho em equipa enquanto trabalhas com programadores experientes que podem orientar-te e partilhar boas práticas. Os teus esforços podem ter um impacto real em ferramentas utilizadas por milhares de pessoas em todo o mundo. Envolveres-te com a nossa comunidade também pode ajudar-te a expandir a tua rede profissional, abrir novas oportunidades e melhorar o teu portefólio, fazendo com que te destaques perante os empregadores.

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

Como começar a contribuir para projetos open source da Ultralytics#

Um excelente ponto de partida é consultar o guia oficial de contribuição da Ultralytics. Está repleto de boas práticas e dicas para te ajudar a tirar o máximo partido das tuas contribuições. O primeiro passo é familiarizares-te com o que já faz parte do projeto, compreendendo as diretrizes de contribuição e explorando o código.

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

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

Diferentes áreas para contribuir#

Depois de configurares o teu ambiente e te familiarizares com o projeto, podes explorar as diferentes áreas onde 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.

Eis algumas opções:

• Documentação: Contribuir para a documentação é uma excelente forma de conheceres o projeto enquanto aperfeiçoas as tuas competências de escrita. Podes ajudar a melhorar a documentação existente, adicionar detalhes 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 variar desde pequenos ajustes até problemas mais complexos, dando-te a oportunidade de causar um impacto concreto no projeto.
• Melhorias de funcionalidades: Para quem está preparado para aprofundar o conhecimento do projeto, trabalhar em melhorias de funcionalidades pode ser desafiante e gratificante. Isto pode envolver adicionar novas funcionalidades, melhorar as existentes ou trabalhar no roteiro do projeto.
• Revisões de pull requests: Rever pull requests é outra forma valiosa de contribuir, especialmente se estiveres familiarizado com os padrões e as boas práticas do projeto. Ao fornecer feedback e sugerir melhorias, ajudas a manter a qualidade e a integridade da base de código.
• Discussões da comunidade: Participar em discussões da comunidade é uma excelente forma de contribuir se gostas de colaborar e partilhar ideias. Participa nas conversas em curso, propõe novas ideias ou ajuda outras pessoas oferecendo os teus conhecimentos e soluções.

Cada uma destas áreas oferece uma forma única de contribuir, e podes escolher a que melhor se alinha com os teus pontos fortes e interesses. Lembra-te de que todas as contribuições, por mais pequenas que sejam, desempenham um papel fundamental no crescimento e na evolução da Ultralytics.

Fig. 2. Todas as contribuições são valorizadas na nossa comunidade em crescimento. Fonte da imagem: Envato Elements.

Contribuir para a documentação open source da Ultralytics#

Ao contribuíres para a documentação da Ultralytics, não te esqueças de rever a documentação existente e verificar se existem problemas ou discussões que destaquem áreas que precisam de melhorias. Isto ajuda a garantir que as tuas contribuições se concentram no que é mais necessário.

Ao escreveres ou editares, tem em mente que é essencial seguir as diretrizes do projeto para manter a consistência. Eis algumas dicas de formatação:

• Utiliza sempre formatação Markdown.
• Começa cada documento com uma introdução clara e utiliza uma linguagem simples e acessível.
• Utiliza listas com marcadores, texto descritivo para as ligações e imagens com menos de 1 MB para permitir que as páginas carreguem rapidamente.
• Se tiveres dúvidas sobre a formatação, uma forma simples de confirmar se está correta é verificar como a documentação anterior foi formatada.

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

Depois de criares o teu rascunho, é importante pré-visualizá-lo compilando a documentação localmente. Podes detetar quaisquer problemas antes de enviar a contribuição. Para isso, começa por clonar o repositório e aceder ao diretório do projeto:

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

Por fim, disponibiliza a documentação localmente para reveres as tuas alterações:

Podes ver a documentação compilada localmente acedendo a http://127.0.0.1:8000/ no teu navegador.

Depois de reveres a clareza, a exatidão e a consistência, podes enviar uma pull request com uma descrição clara da documentação que criaste. Coloca a documentação na secção adequada, com base no local a que pertence e onde melhor se enquadra (guias, soluções, integrações, etc.). Consulta também o ficheiro index.md para veres as secções relevantes e o ficheiro mkdocs.yml geral, fazendo as atualizações necessárias. A atenção aos detalhes ajudará a que o processo de revisão decorra sem problemas e garantirá que a tua contribuição fica bem integrada no projeto.

Aspetos a ter em conta ao contribuir para código open source#

Ao fazeres contribuições de código para o projeto Ultralytics, é importante seguir boas práticas que ajudem a garantir que o teu código é limpo, fácil de manter e simples de integrar. Eis alguns pontos importantes a ter em conta:

• Evita a duplicação de código: Reutiliza o código existente sempre que possível e minimiza os argumentos desnecessários.
• Faz alterações mais pequenas e focadas: Concentra-te em alterações menores e direcionadas, em vez de modificações de grande dimensão.
• Simplifica ou remove código: Procura oportunidades para simplificar o código ou remover partes desnecessárias.
• Escreve docstrings eficazes: Explica claramente o que o teu código faz e inclui ligações para recursos relevantes.
• Evita dependências desnecessárias: Adiciona dependências apenas se forem absolutamente necessárias.

Fig. 4. Boas práticas de documentação do código-fonte.

Também é essencial considerar a facilidade de manutenção da base de código a longo prazo. Antes de fazeres alterações, pergunta a ti próprio se as tuas modificações podem quebrar o código existente de alguém que esteja a utilizar a Ultralytics. Se for esse o caso, considera como resolver a situação e garante que as tuas alterações são tão compatíveis quanto possível.

Depois de desenvolveres um trecho de código para contribuir, terás de o testar. Podes utilizar frameworks como o pytest para testar as tuas alterações antes de as enviares. A formatação consistente do código é outro aspeto muito importante da tua contribuição. Ferramentas como o Ruff Formatter podem ajudar-te a manter a consistência estilística e a detetar erros lógicos ou inconsistências no teu código.

Rever pull requests#

Rever pull requests (PRs) é uma excelente forma de contribuir! É criada uma PR quando alguém solicita a integração das suas alterações no projeto principal. Isto ajuda a manter o projeto Ultralytics a funcionar sem problemas. Ao reveres uma PR, certifica-te de que compreendes por que motivo as alterações foram feitas. O autor deve explicar claramente o objetivo e os benefícios da atualização, e deves encontrar evidências de testes completos na respetiva PR.

Fig. 5. O que é uma pull request?

Vamos analisar alguns pontos importantes nos quais deves concentrar-te.

• Verifica os testes unitários: Confirma que a PR inclui testes para novas funcionalidades ou alterações, de modo a confirmar que o código funciona conforme esperado e não introduz problemas.
• Revê as atualizações da documentação: Verifica se a documentação foi atualizada para refletir alterações ou novas funcionalidades, incluindo exemplos, referências da API e outros detalhes relevantes.
• Avalia o impacto no desempenho: Considera de que forma as alterações afetam o desempenho. Se necessário, solicita benchmarks de desempenho ou testes adicionais.
• Verifica os testes de CI: Garante que todos os testes de Integração Contínua (CI) são aprovados, incluindo as verificações de formatação do código e os resultados dos testes unitários.
• Colabora nas correções: Se algum teste falhar, trabalha com o autor para resolver os problemas antes de aprovares a PR.

Enquanto revisor, certifica-te de que forneces feedback específico e claro sobre quaisquer problemas ou preocupações. Oferece sugestões de melhoria e faz perguntas que ajudem o autor a refletir sobre potenciais problemas. Incentiva-o a seguir boas práticas de programação, testes e documentação, e não hesites em indicar-lhe recursos que possam ajudar. Por último, reconhece sempre o esforço que o autor dedicou à PR. O feedback positivo ajuda a manter um ambiente amigável e colaborativo na comunidade open source.

Contribuir é sobretudo uma questão de comunidade#

Contribuir para projetos open source como os da Ultralytics pode proporcionar-te um inspirador sentido de comunidade. Quer estejas a escrever código, a rever PRs, a atualizar documentação ou a participar em discussões, todos os esforços ajudam o projeto a crescer e a evoluir. Responder a problemas ou participar em conversas, seja no GitHub, no Discord, no Subreddit ou noutros fóruns, é uma forma valiosa de contribuir e de te ligares a outras pessoas. Lembra-te de que as tuas contribuições, por mais pequenas que sejam, têm um impacto significativo e ajudam a promover um ambiente colaborativo e solidário para todas as pessoas envolvidas!

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 repositório do GitHub. Junta-te à nossa comunidade dinâmica e vê como estamos a causar impacto em setores como a agricultura e a indústria transformadora.