Um guia para começar a contribuir em open source.
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.
- Código
- Adicionar funcionalidades
- Consertar bugs
- Conteúdo
- Design gráfico
- Tradução
- Documentação
- Usabilidade
- Comunidade
- Tirar dúvidas
- Triagem etc...
- Experiência no mundo real
- Colaboração em equipes grandes
- Exposição a boas práticas da indústria
- Portfólio
- Dinheiro
- 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
👣👣👣👣👣👣👣👣👣👣👣👣
- Organizações participando do Google Summer of Code
- Tópicos no GitHub
🔥 Ignition Robotics
🐢 ROS 2
- Se ainda não é usuário, use!
- Faça tutoriais
- Rode exemplos
- Faça perguntas
🔥 Ignition Robotics
🐢 ROS 2
- Faça uma busca
- Fóruns
- Chats (IRC, Slack...)
- Mailing lists
- Arquivo
CONTRIBUTING.md
🔥 Ignition Robotics
🐢 ROS 2
- 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
- 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
- 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) oumaster - Os headers ficam em
include, a implementação emsrc - Os testes ficam em
testesrce 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 emsrce testes emtest - Lembre de assinar as commits (
git commit -s)
- 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(oubuild/<pacote>/bincom 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>
- 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
- ROS 2: Code style and language versions
- Os pacotes principais do ROS 2 têm todo seu estilo checado por linters.
- Rodam como parte dos testes.
- Documentação para APIs novas
- Comentários no código
- Exemplos de como usar
- Tutoriais, vídeos...
🔥 Ignition Robotics
- APIs são documentadas usando Doxygen e publicadas online em Ignition Robotics: Development libraries.
- Tutoriais globais ficam no ignitionrobotics/docs e são publicados online em Ignition Robotics: Docs.
- Tutoriais para cada biblioteca ficam na pasta
tutorialse são publicados junto às APIs em Ignition Robotics: Development libraries.
🐢 ROS 2
- APIs são documentadas usando Doxygen e algumas são publicadas online em http://docs.ros2.org.
- Tutoriais globais ficam no ros2/ros2_documentation e são publicados no ROS Index.
- 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
- Por exemplo, veja os pull requests mergidos no ign-gazebo.
- O resultado dos testes será linkado na interface do GitHub
🐢 ROS 2
- Por exemplo, veja os pull requests mergidos no rclcpp.
- 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
- 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:
- Comece a desenvolver projetos open source (março de 2016).