└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Código aberto em 12 passos 👣🔓 2 | 3 | Um guia para começar a contribuir em open source. 4 | 5 | ## Para quem é esse guia? 6 | 7 | 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/). 8 | 9 | ## Formas de colaborar 10 | 11 | * Código 12 | * Adicionar funcionalidades 13 | * Consertar bugs 14 | * Conteúdo 15 | * Design gráfico 16 | * Tradução 17 | * Documentação 18 | * Usabilidade 19 | * Comunidade 20 | * Tirar dúvidas 21 | * Triagem 22 | etc... 23 | 24 | ## O que você ganha colaborando? 25 | 26 | * Experiência no mundo real 27 | * Colaboração em equipes grandes 28 | * Exposição a boas práticas da indústria 29 | * Portfólio 30 | * Dinheiro 31 | 32 | ## O que você precisa para começar? 33 | 34 | * Inglês 35 | * Ler e escrever 36 | * Ninguém está preocupado com sua gramática. O importante é se comunicar. 37 | * Existem projetos sendo desenvolvidos em português, mas a grande maioria dos projetos desenvolvidos no mundo inteiro são em inglês. 38 | * Controle de versão ([git](https://git-scm.com/)) 39 | * Habilidades específicas de cada projeto 40 | 41 | 👣👣👣👣👣👣👣👣👣👣👣👣 42 | 43 | # 12 passos 44 | 45 | # 1 👣 Escolher o software 46 | 47 | * Organizações participando do [Google Summer of Code](https://summerofcode.withgoogle.com/organizations/) 48 | * [Tópicos no GitHub](https://github.com/topics) 49 | 50 |
51 | 🔥 Ignition Robotics 52 | 53 | [IgnitionRobotics.org](https://ignitionrobotics.org) 54 |
55 | 56 |
57 | 🐢 ROS 2 58 | 59 | [ROS 2 Documentation](https://index.ros.org/doc/ros2/) 60 |
61 | 62 | # 2 👣 Familiarizar-se com o software 63 | 64 | * Se ainda não é usuário, use! 65 | * Faça tutoriais 66 | * Rode exemplos 67 | * Faça perguntas 68 | 69 |
70 | 🔥 Ignition Robotics 71 | 72 | * [Tutoriais: Ignition Citadel](https://ignitionrobotics.org/docs/citadel/gui) 73 | * [Tutoriais: Ignition Gazebo](https://ignitionrobotics.org/api/gazebo/3.0/tutorials.html) 74 | * [Gazebo Answers](https://answers.gazebosim.org/) 75 |
76 | 77 |
78 | 🐢 ROS 2 79 | 80 | * [Tutoriais: ROS 2](https://index.ros.org/doc/ros2/Tutorials/#tutorials) 81 | * [ROS Answers](https://answers.ros.org/) 82 |
83 | 84 | # 3 👣 Descobrir processo de contribuição 85 | 86 | * Faça uma busca 87 | * Fóruns 88 | * Chats (IRC, Slack...) 89 | * Mailing lists 90 | * Arquivo `CONTRIBUTING.md` 91 | 92 |
93 | 🔥 Ignition Robotics 94 | 95 | * [Contributing to Ignition Robotics](https://ignitionrobotics.org/docs/all/contributing) 96 |
97 | 98 |
99 | 🐢 ROS 2 100 | 101 | * [Contributing: ROS 2](https://index.ros.org/doc/ros2/Contributing/) 102 |
103 | 104 | # 4 👣 Escolher como contribuir 105 | 106 | * Lista de problemas (issue tracker) 107 | * Pergunte se alguém já começou a fazer o que você quer fazer, se tem dicas, sugestões... 108 | 109 |
110 | 🔥 Ignition Robotics 111 | 112 | * [Ignition Robotics: good first issues](https://github.com/search?q=org%3Aignitionrobotics+label%3A%22good+first+issue%22&type=Issues) 113 | * [Ignition Robotics: todos os issues](https://github.com/search?q=org%3Aignitionrobotics&state=open&type=Issues) 114 |
115 | 116 |
117 | 🐢 ROS 2 118 | 119 | * [ROS 2: good first issues](https://github.com/search?q=org%3Aros2+label%3A%22good+first+issue%22&type=Issues) 120 | * [ROS 2: help wanted](https://github.com/search?q=org%3Aros2+label%3A%22help+wanted%22&type=Issues) 121 |
122 | 123 | # 5 👣 Familiarizar-se com o código 124 | 125 | * Organização do código 126 | * Workflow 127 | * Tente mudar qualquer coisinha pra ver se funciona 128 | 129 |
130 | 🔥 Ignition Robotics 131 | 132 | Recomendações: 133 | 134 | * Clone e compile todas as bibliotecas (leva uma meia hora) 135 | * Use [colcon](https://colcon.readthedocs.io/) para manter seu código isolado 136 | * Não misture instalação de binários com instalação da fonte 137 |
138 | 139 |
140 | 🐢 ROS 2 141 | 142 | Recomendações: 143 | 144 | * Clone e compile somente os pacotes necessários 145 | * Desinstale binários desses pacotes 146 |
147 | 148 | # 6 👣 Programar! 149 | 150 | * Escolha o "branch" por onde começar 151 | * Crie um "branch" separado 152 | * [grep](https://pt.wikipedia.org/wiki/Grep)e muito! 153 | * Não tente entender tudo! 154 | * Organize as `commit`s 155 | 156 |
157 | 🔥 Ignition Robotics 158 | 159 | * Comece de um "release branch" (`ign-N`) ou `master` 160 | * Os headers ficam em `include`, a implementação em `src` 161 | * Os testes ficam em `test` e `src` e terminam com `_TEST.cc` 162 | * Cada biblioteca tem uma pasta de exemplos, `examples` 163 | * Lembre de assinar as commits (`git commit -s`) 164 |
165 | 166 |
167 | 🐢 ROS 2 168 | 169 | * Comece do branch padrão, geralmente `master` 170 | * Os headers ficam em `include`, a implementação em `src` e testes em `test` 171 | * Lembre de assinar as commits (`git commit -s`) 172 |
173 | 174 | # 7 👣 Testes 175 | 176 | * Escreva testes para que o problema não volte no futuro 177 | * Verifique que não quebrou nenhum teste existente 178 | * Verifique que não introduziu avisos (warnings) 179 | * Muitos projetos iniciam testes automaticamente (CI, continuous integration) 180 | 181 |
182 | 🔥 Ignition Robotics 183 | 184 | * Quando fizer o pull request, seu código será testado em todas as plataformas (Linux, OSX, Windows) 185 | * Os testes ficam em `build/bin` (ou `build//bin` com colcon) 186 | * Rode todos os testes da biblioteca com `make test` / `colcon test --package-select ` 187 | * Rode testes individuais com `./build/bin/` 188 |
189 | 190 |
191 | 🐢 ROS 2 192 | 193 | * Se fizer um pull request ao branch `master`, um membro da organização irá iniciar CI manualmente 194 | * Rode todos os testes do pacote com `colcon test --package-select ` 195 | * Rode testes individuais com `./build//bin/` 196 |
197 | 198 | # 8 👣 Estilo 199 | 200 | * Tente manter o estilo atual do projeto (nomes de funções, indentação...) 201 | * Siga o estilo oficial, se houver 202 | * Tente mudar somente o necessário para facilitar a revisão 203 | * Certifique-se que os linters estão passando 204 | 205 |
206 | 🔥 Ignition Robotics 207 | 208 | * [Ignition style guide](https://ignitionrobotics.org/docs/all/contributing#style-guides) 209 | * Vários aspectos do estilo não são checados por linters e podem ser apontados durante a revisão. 210 | * Teste com `bash tools/code_check.sh` 211 |
212 | 213 |
214 | 🐢 ROS 2 215 | 216 | * [ROS 2: Code style and language versions](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/) 217 | * Os pacotes principais do ROS 2 têm todo seu estilo checado por linters. 218 | * Rodam como parte dos testes. 219 |
220 | 221 | # 9 👣 Documentação 222 | 223 | * Documentação para APIs novas 224 | * Comentários no código 225 | * Exemplos de como usar 226 | * Tutoriais, vídeos... 227 | 228 |
229 | 🔥 Ignition Robotics 230 | 231 | * APIs são documentadas usando [Doxygen](https://www.doxygen.nl/) e publicadas online em [Ignition Robotics: Development libraries](https://ignitionrobotics.org/libs). 232 | * 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). 233 | * Tutoriais para cada biblioteca ficam na pasta `tutorials` e são publicados junto às APIs em [Ignition Robotics: Development libraries](https://ignitionrobotics.org/libs). 234 |
235 | 236 |
237 | 🐢 ROS 2 238 | 239 | * 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). 240 | * 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/). 241 |
242 | 243 | # 10 👣 Pull request 244 | 245 | * Veja outros pull requests como exemplo da cultura do projeto 246 | * Explique bem o que foi feito na descrição, qual problema está sendo resolvido e como testar a solução 247 | * Facilite ao máximo a vida de quem vai revisar 248 | * Se possível, divida em pedaços menores (vários pull requests) 249 | 250 |
251 | 🔥 Ignition Robotics 252 | 253 | * Por exemplo, veja os [pull requests mergidos no ign-gazebo](https://github.com/ignitionrobotics/ign-gazebo/pulls?q=is%3Apr+is%3Aclosed+review%3Aapproved). 254 | * O resultado dos testes será linkado na interface do GitHub 255 |
256 | 257 |
258 | 🐢 ROS 2 259 | 260 | * Por exemplo, veja os [pull requests mergidos no rclcpp](https://github.com/ros2/rclcpp/pulls?q=is%3Apr+is%3Aclosed+review%3Aapproved). 261 |
262 | 263 | # 11 👣 Revisão 264 | 265 | * Responda comentários 266 | * Faça as mudanças necessárias 267 | * Pode levar desde horas até meses! 268 | * Seja educad@! 269 | 270 |
271 | 🔥 Ignition Robotics 272 | 273 | * Requer ao menos uma aprovação de um mantenedor 274 |
275 | 276 |
277 | 🐢 ROS 2 278 | 279 | * Requer ao menos uma aprovação de um mantenedor 280 |
281 | 282 | # 12 👣 Merge 283 | 284 | * Seu código passa a fazer parte do código fonte oficial 285 | * Seu código aparecerá no próximo release oficial 286 | * Agora os mantenedores sdo projeto manterão seu código, e você também pode ficar de olho caso apareçam problemas 287 | * 🍾 288 | 289 |
290 | 🔥 Ignition Robotics 291 | 292 | * Se fez o pull request em um branch `ign-N`, seu código sairá no próximo release "minor" ou "patch". 293 | * Se foi ao `master`, sairá no próximo release "major". 294 |
295 | 296 |
297 | 🐢 ROS 2 298 | 299 | * Se fez o pull request em um release branch, seu código sairá no próximo "sync" ou "patch". 300 | * Se foi ao `master`, sairá na próxima distribuição. 301 |
302 | 303 | --- 304 | 305 | Este guia foi escrito para a Meetup ROS Brasil em maio de 2020. 306 | 307 | Apresentação anterior: 308 | 309 | * [Comece a desenvolver projetos open source](https://www.youtube.com/watch?v=H0baE1LGsks) (março de 2016). 310 | --------------------------------------------------------------------------------