/guia_codigo_aberto

Um guia para começar a contribuir em open source

Código aberto em 12 passos 👣🔓

Um guia para começar a contribuir em open source.

Para quem é esse guia?

Quem quer contribuir com open-source mas não sabe por onde começar. Foco em contribuição de código para os projetos Ignition Robotics e ROS 2.

Formas de colaborar

  • Código
    • Adicionar funcionalidades
    • Consertar bugs
  • Conteúdo
    • Design gráfico
    • Tradução
    • Documentação
    • Usabilidade
  • Comunidade
    • Tirar dúvidas
    • Triagem etc...

O que você ganha colaborando?

  • Experiência no mundo real
  • Colaboração em equipes grandes
  • Exposição a boas práticas da indústria
  • Portfólio
  • Dinheiro

O que você precisa para começar?

  • Inglês
    • Ler e escrever
    • Ninguém está preocupado com sua gramática. O importante é se comunicar.
    • Existem projetos sendo desenvolvidos em português, mas a grande maioria dos projetos desenvolvidos no mundo inteiro são em inglês.
  • Controle de versão (git)
  • Habilidades específicas de cada projeto

👣👣👣👣👣👣👣👣👣👣👣👣

12 passos

1 👣 Escolher o software

🔥 Ignition Robotics

IgnitionRobotics.org

🐢 ROS 2

ROS 2 Documentation

2 👣 Familiarizar-se com o software

  • Se ainda não é usuário, use!
  • Faça tutoriais
  • Rode exemplos
  • Faça perguntas
🔥 Ignition Robotics
🐢 ROS 2

3 👣 Descobrir processo de contribuição

  • Faça uma busca
  • Fóruns
  • Chats (IRC, Slack...)
  • Mailing lists
  • Arquivo CONTRIBUTING.md
🔥 Ignition Robotics
🐢 ROS 2

4 👣 Escolher como contribuir

  • Lista de problemas (issue tracker)
  • Pergunte se alguém já começou a fazer o que você quer fazer, se tem dicas, sugestões...
🔥 Ignition Robotics
🐢 ROS 2

5 👣 Familiarizar-se com o código

  • Organização do código
  • Workflow
  • Tente mudar qualquer coisinha pra ver se funciona
🔥 Ignition Robotics

Recomendações:

  • Clone e compile todas as bibliotecas (leva uma meia hora)
  • Use colcon para manter seu código isolado
  • Não misture instalação de binários com instalação da fonte
🐢 ROS 2

Recomendações:

  • Clone e compile somente os pacotes necessários
  • Desinstale binários desses pacotes

6 👣 Programar!

  • Escolha o "branch" por onde começar
  • Crie um "branch" separado
  • grepe muito!
  • Não tente entender tudo!
  • Organize as commits
🔥 Ignition Robotics
  • Comece de um "release branch" (ign-<biblioteca>N) ou master
  • Os headers ficam em include, a implementação em src
  • Os testes ficam em test e src e terminam com _TEST.cc
  • Cada biblioteca tem uma pasta de exemplos, examples
  • Lembre de assinar as commits (git commit -s)
🐢 ROS 2
  • Comece do branch padrão, geralmente master
  • Os headers ficam em include, a implementação em src e testes em test
  • Lembre de assinar as commits (git commit -s)

7 👣 Testes

  • Escreva testes para que o problema não volte no futuro
  • Verifique que não quebrou nenhum teste existente
  • Verifique que não introduziu avisos (warnings)
  • Muitos projetos iniciam testes automaticamente (CI, continuous integration)
🔥 Ignition Robotics
  • Quando fizer o pull request, seu código será testado em todas as plataformas (Linux, OSX, Windows)
  • Os testes ficam em build/bin (ou build/<pacote>/bin com colcon)
  • Rode todos os testes da biblioteca com make test / colcon test --package-select <pacote>
  • Rode testes individuais com ./build/bin/<teste>
🐢 ROS 2
  • Se fizer um pull request ao branch master, um membro da organização irá iniciar CI manualmente
  • Rode todos os testes do pacote com colcon test --package-select <pacote>
  • Rode testes individuais com ./build/<pacote>/bin/<teste>

8 👣 Estilo

  • Tente manter o estilo atual do projeto (nomes de funções, indentação...)
  • Siga o estilo oficial, se houver
  • Tente mudar somente o necessário para facilitar a revisão
  • Certifique-se que os linters estão passando
🔥 Ignition Robotics
  • Ignition style guide
  • Vários aspectos do estilo não são checados por linters e podem ser apontados durante a revisão.
  • Teste com bash tools/code_check.sh
🐢 ROS 2

9 👣 Documentação

  • Documentação para APIs novas
  • Comentários no código
  • Exemplos de como usar
  • Tutoriais, vídeos...
🔥 Ignition Robotics
🐢 ROS 2

10 👣 Pull request

  • Veja outros pull requests como exemplo da cultura do projeto
  • Explique bem o que foi feito na descrição, qual problema está sendo resolvido e como testar a solução
  • Facilite ao máximo a vida de quem vai revisar
  • Se possível, divida em pedaços menores (vários pull requests)
🔥 Ignition Robotics
🐢 ROS 2

11 👣 Revisão

  • Responda comentários
  • Faça as mudanças necessárias
  • Pode levar desde horas até meses!
  • Seja educad@!
🔥 Ignition Robotics
  • Requer ao menos uma aprovação de um mantenedor
🐢 ROS 2
  • Requer ao menos uma aprovação de um mantenedor

12 👣 Merge

  • Seu código passa a fazer parte do código fonte oficial
  • Seu código aparecerá no próximo release oficial
  • Agora os mantenedores sdo projeto manterão seu código, e você também pode ficar de olho caso apareçam problemas
  • 🍾
🔥 Ignition Robotics
  • Se fez o pull request em um branch ign-<biblioteca>N, seu código sairá no próximo release "minor" ou "patch".
  • Se foi ao master, sairá no próximo release "major".
🐢 ROS 2
  • Se fez o pull request em um release branch, seu código sairá no próximo "sync" ou "patch".
  • Se foi ao master, sairá na próxima distribuição.

Este guia foi escrito para a Meetup ROS Brasil em maio de 2020.

Apresentação anterior: