Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/chapulina/guia_codigo_aberto

Um guia para começar a contribuir em open source
https://github.com/chapulina/guia_codigo_aberto

Last synced: 2 months ago
JSON representation

Um guia para começar a contribuir em open source

Lists

README

        

# 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](https://ignitionrobotics.org) e [ROS 2](https://index.ros.org/doc/ros2/).

## 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](https://git-scm.com/))
* Habilidades específicas de cada projeto

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

# 12 passos

# 1 👣 Escolher o software

* Organizações participando do [Google Summer of Code](https://summerofcode.withgoogle.com/organizations/)
* [Tópicos no GitHub](https://github.com/topics)

🔥 Ignition Robotics

[IgnitionRobotics.org](https://ignitionrobotics.org)

🐢 ROS 2

[ROS 2 Documentation](https://index.ros.org/doc/ros2/)

# 2 👣 Familiarizar-se com o software

* Se ainda não é usuário, use!
* Faça tutoriais
* Rode exemplos
* Faça perguntas

🔥 Ignition Robotics

* [Tutoriais: Ignition Citadel](https://ignitionrobotics.org/docs/citadel/gui)
* [Tutoriais: Ignition Gazebo](https://ignitionrobotics.org/api/gazebo/3.0/tutorials.html)
* [Gazebo Answers](https://answers.gazebosim.org/)

🐢 ROS 2

* [Tutoriais: ROS 2](https://index.ros.org/doc/ros2/Tutorials/#tutorials)
* [ROS Answers](https://answers.ros.org/)

# 3 👣 Descobrir processo de contribuição

* Faça uma busca
* Fóruns
* Chats (IRC, Slack...)
* Mailing lists
* Arquivo `CONTRIBUTING.md`

🔥 Ignition Robotics

* [Contributing to Ignition Robotics](https://ignitionrobotics.org/docs/all/contributing)

🐢 ROS 2

* [Contributing: ROS 2](https://index.ros.org/doc/ros2/Contributing/)

# 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

* [Ignition Robotics: good first issues](https://github.com/search?q=org%3Aignitionrobotics+label%3A%22good+first+issue%22&type=Issues)
* [Ignition Robotics: todos os issues](https://github.com/search?q=org%3Aignitionrobotics&state=open&type=Issues)

🐢 ROS 2

* [ROS 2: good first issues](https://github.com/search?q=org%3Aros2+label%3A%22good+first+issue%22&type=Issues)
* [ROS 2: help wanted](https://github.com/search?q=org%3Aros2+label%3A%22help+wanted%22&type=Issues)

# 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](https://colcon.readthedocs.io/) 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
* [grep](https://pt.wikipedia.org/wiki/Grep)e muito!
* Não tente entender tudo!
* Organize as `commit`s

🔥 Ignition Robotics

* Comece de um "release branch" (`ign-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//bin` com colcon)
* Rode todos os testes da biblioteca com `make test` / `colcon test --package-select `
* Rode testes individuais com `./build/bin/`

🐢 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 `
* Rode testes individuais com `./build//bin/`

# 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](https://ignitionrobotics.org/docs/all/contributing#style-guides)
* 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](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/)
* Os pacotes principais do ROS 2 têm todo seu estilo checado por linters.
* Rodam como parte dos testes.

# 9 👣 Documentação

* 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](https://www.doxygen.nl/) e publicadas online em [Ignition Robotics: Development libraries](https://ignitionrobotics.org/libs).
* Tutoriais globais ficam no [ignitionrobotics/docs](https://github.com/ignitionrobotics/docs) e são publicados online em [Ignition Robotics: Docs](https://ignitionrobotics.org/docs/citadel).
* Tutoriais para cada biblioteca ficam na pasta `tutorials` e são publicados junto às APIs em [Ignition Robotics: Development libraries](https://ignitionrobotics.org/libs).

🐢 ROS 2

* APIs são documentadas usando [Doxygen](https://www.doxygen.nl/) e algumas são publicadas online em [http://docs.ros2.org](http://docs.ros2.org/eloquent/api/rcutils/index.html).
* Tutoriais globais ficam no [ros2/ros2_documentation](https://github.com/ros2/ros2_documentation) e são publicados no [ROS Index](https://index.ros.org/doc/ros2/).

# 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

* Por exemplo, veja os [pull requests mergidos no ign-gazebo](https://github.com/ignitionrobotics/ign-gazebo/pulls?q=is%3Apr+is%3Aclosed+review%3Aapproved).
* O resultado dos testes será linkado na interface do GitHub

🐢 ROS 2

* Por exemplo, veja os [pull requests mergidos no rclcpp](https://github.com/ros2/rclcpp/pulls?q=is%3Apr+is%3Aclosed+review%3Aapproved).

# 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-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](https://www.youtube.com/watch?v=H0baE1LGsks) (março de 2016).