O documento fornece instruções sobre como colaborar com projetos de código aberto, incluindo como começar a contribuir com um projeto existente através de relatórios de bugs, solicitações de recursos ou envio de código, além de discutir ferramentas como Git, GitHub e licenças de software livre.

1. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
ProjetosProjetos
Open Source,Open Source,
Como colaborar?Como colaborar?

2. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Getting started
● Como começar?
– Iniciar do zero
– Projeto já existente
● Que conhecimentos são necessários?
– Conhecer o projeto!
– Depende da contribuição
● Terminologia
– Fork, branch, repositório, issues, testes, CI, ...

3. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Como colaborar com um projeto
existente?
● Issues
– Bug report
– Feature request
● Código
– Testes
● Documentação
– Traduções
● Divulgação
– Avaliação
● Uso
– Relatos (e.g. blog)
– Criação de “plugins”
● Doações
● ...

4. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Issues
● Bug report
– Reprodutibilidade!
– Versão usada
– Resultado e expectativa
– Passos que reproduzem
o bug
● Anexar dados utilizados
nos passos
– Exemplo:
http://savannah.gnu.org/b
ugs/?func=detailitem&item
_id=42519
● Feature request
– Público-alvo / potencial de
utilização
– Compatibilidade com o
que existe
– “Design” da mudança
● Outras propostas
– Pull-requests
– Otimização
– Fusão de projetos
– ...
Não precisa [saber]
programar!

5. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Divulgação e avaliação
● Stars / likes
– Aumentam visibilidade
● Relato de uso
– Blog
– YouTube
– ...
● Material didático
– Tutoriais
– Livros
– Vídeo-aulas
– Cursos
https://github.com/explore
Traduções?
EVENTOS!
Agitar a galera!

6. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
ÉÉ
precisopreciso
ver aosver aos
poucos!poucos!
Git
Controle de versão distribuído●
git initgit init
– Cria um repositório no diretório atualCria um repositório no diretório atual
●
git addgit add
– Marca um arquivo como “staged” para “commit”Marca um arquivo como “staged” para “commit”
●
git commitgit commit
– Insere uma atualização no repositório na forma de um “commit” com os dados “staged”. Parâmetro “-a” para todasInsere uma atualização no repositório na forma de um “commit” com os dados “staged”. Parâmetro “-a” para todas
as modificações de arquivos já inseridos.as modificações de arquivos já inseridos.
●
git pullgit pull
– Obtém os dados do remote, atualizando o repositório localObtém os dados do remote, atualizando o repositório local
●
git pushgit push
– Atualiza (append-like) a branch (ramificação) no servidor (remote) com os dados locaisAtualiza (append-like) a branch (ramificação) no servidor (remote) com os dados locais
●
git resetgit reset
– Limpa a área de “staging” ou retrocede commits (não usar após push)Limpa a área de “staging” ou retrocede commits (não usar após push)
●
git remotegit remote
– Insere um host (servidor) para “push”Insere um host (servidor) para “push”
●
git configgit config
– Altera configurações (usuário, e-mail, editor padrão para mensagens dos commit, etc.). 3 níveis: local (repositório),Altera configurações (usuário, e-mail, editor padrão para mensagens dos commit, etc.). 3 níveis: local (repositório),
usuário e global (sistema)usuário e global (sistema)
●
git statusgit status
– Exibe informações sobre o que está “staged”, arquivos alterados e arquivos que estão no diretório mas nãoExibe informações sobre o que está “staged”, arquivos alterados e arquivos que estão no diretório mas não
pertencem ao repositóriopertencem ao repositório
●
git loggit log
– Exibe as mensagens e outros detalhes dos commits realizadosExibe as mensagens e outros detalhes dos commits realizados
●
git diffgit diff
– Exibe diferenças de código entre commits ou entre o último commit e os dados atuaisExibe diferenças de código entre commits ou entre o último commit e os dados atuais
●
git checkout / branch / merge / mergetool / taggit checkout / branch / merge / mergetool / tag
– Usados em branching, versionamento, etc.Usados em branching, versionamento, etc.
●
……
– fetch, stash, rebase, reflog, subtree, submodule, ...fetch, stash, rebase, reflog, subtree, submodule, ...
● Apareça nos dojos!!!
– https://github.com/Dojo-
SP
● O GitHub fornece os
comandos em várias
situações
– Criação de repositório
– Merge (pull-request)
● Muita documentação
disponível
!!!
https://help.github.com/articles/good-resources-for-learning-git-and-github/

7. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
GUI para o git?
gitk

8. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
GitHub
Hospedagem e rede social
● Organizações
● Followers (seguidores)
● Stars (likes/curtidas)
● Histórico de atividades
– News feed
– “Quadradinhos”
● Estatísticas
● Comentários
● Issues
● Watch
● Fork!!!
● “Exibição” do
repositório/diretório
– README
– Markdown: README.md
– reStructuredText: README.rst

9. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Mais issues!
(Organização no GitHub)
● Status
– Open
– Merged
– Closed
● Issues
– Não fazem parte do
repositório git
– Fazem parte do projeto
no GitHub
● Pull-requests
– Envio de código
– Fork
– Totalmente via interface Web
● Colaboradores
– Podem aplicar mudanças no
código sem usar o
mecanismo de pull-requests
– Mudança no status das
issues

10. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Fork
● Branch
– Ramificação
– Experimentação
● Merge
– União de branches
● Fork
– Uma “cópia” do projeto
– Pode caracterizar outro
projeto
● Clone
– Cópia [local] do
repositório (git clone)
– Não caracteriza outro
projeto
Fork famoso: pillow (fork que continuou
o PIL - Python Imaging Library)

11. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Pull-request
“tradição”
1)Fazer um fork do projeto
2)Copiar conteúdo do fork para a máquina local
...git clone / git pull
3)Efetuar a alteração desejada em uma branch do
fork
4)Atualizar conteúdo no fork
...git push
5)Solicitar o PR (pull-request) pela Web UI
...há um “git merge” implícito

12. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Aspectos sociais das colaborações
(pull-requests e outras issues)
● Alterações no comportamento do software
– Necessário avisar o autor antes de fazer o pull-request (ou
antes de “encostar no código”)
● Bugfix / new feature
– Aviso prévio é opcional, mas permite
● Brainstorming
● Evitar escrever código que será recusado
● Expectativa
● Em certos projetos (e.g. MongoDB), há um contrato
(pessoal) p/ aceitação de PRs
A rigor, a licença já permite a alteração do código. Essa
comunicação se refere à intenção de incorporação de seu
código ao projeto original, i.e., como algo além de um fork.

13. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Estilo
● Aspectos “cosméticos”
– Evite conflitos!
– Não mande um PR puramente “cosmético” a menos que
isso já esteja combinado com os colaboradores do projeto
● Idioma
– Manter o do projeto, se possível
– Inglês costuma ser adotado na maioria dos projetos
– Isso vale para issues, comentários, nomes de variáveis,
etc.
PEP8?
“Solução” única...
para qual
problema?

14. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Projetos convidativos a novos
colaboradores
● Sinalização através de issues fáceis (requisitadas pela própria
“equipe” do projeto)
– Estilo (código)
– Tradução
– Gramática/ortografia em comentários e documentação
– Atividades “braçais” / repetitivas / triviais (e.g. inserir shebang em todos os
arquivos de exemplo)
● Talvez automatizáveis com shell script
– Testes
● Incrementar a cobertura de código
– Oneliners
– Documentação extra / novos exemplos
● Auxilia no aprendizado com o ambiente social, com os softwares
envolvidos, etc.

15. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Stash / Rebase
(comandos do git)
● É muito comum algo ser feito e desfeito entre commits de
uma branch, ou incluir commits separados de “ajustes
cosméticos”
● Estatísticas do GitHub coletam:
– Número de commits
– Linhas inseridas
– Linhas removidas
● É muito fácil ser “cheater”, e PRs de cheaters normalmente
não são bem-vindos
● Stash/rebase podem ser usados para “ajustar” o histórico de
uma branch antes do merge na branch principal
(normalmente “master”)
Minha colaboração no hipsterplotMinha colaboração no hipsterplot

16. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Iniciar um projeto “do zero”?
● Sem “legado”
● Controle de versão
– Git
– Mercurial
● Experimentação
● Crowdfunding?
– Não pense nisso em
seu primeiro projeto...
● Compatibilidade
– Python 2 ou 3?
● Aonde colocar?
– GitHub
– BitBucket
– Gitorious
– ...
● Que licença utilizar?

17. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
“Open Source” ou “Free Software”?
● OSI – Open Source Initiative
– http://opensource.org/
● FSF – Free Software
Foundation
– http://www.fsf.org/
– https://gnu.org/
● Critérios e definições do
que é “livre”/”aberto”
● Licenças de software
– GPL, MIT, BSD, etc.
– Compatibilidade

18. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Licença
● NÃO ESCREVA A SUA!
...a menos que
seja/contrate um
advogado...
● [Strong] Copyleft /
“Share-alike”
– GPL v2 (GNU General
Public License)
– GPL v3
– AGPL (Affero GPL)
● Weak Copyleft
– LGPL (Library/Lesser
GPL)
● Permissivas
– MIT
– BSD
– PSFL (Python
Software Foundation
License)
Wikipedia
tem muita
informação
útil...

19. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
PyPI – Python
Package Index
● http://pypi.python.org/
● Pacotes/bibliotecas externas
– Muitos projetos possuem o link do repositório
● Recomenda a utilização do pip
● Utilização de arquivos setup.py
● Tags de classificação em “List trove classifiers”
● Quem faz o upload normalmente é o responsável pelo
projeto, e não tem vínculo com o repositório no GitHub

20. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Testes e Integração Contínua (CI)
● Rodar os testes a cada “push”
– Uma máquina virtual para cada possível ambiente (e.g.
CPython 2.7, CPython 3.4 e PyPy)
– Travis CI
● Cobertura de código
– Coveralls
● Pins
– Permitem registrar em imagens o estado do CI no README do
projeto (como links, contendo relatórios completos)
– PyPI possui pins acerca do número de downloads recente

21. Danilo J. S. Bellini – @danilobellini – São Paulo – SP
Projetos Open Source, como colaborar? – 2015-03-14
Até a próxima!
● Get started! Outras recomendações:
– GitHub
● https://help.github.com/articles/set-up-git/
● https://help.github.com/articles/create-a-repo/
● https://help.github.com/articles/fork-a-repo
● https://help.github.com/articles/be-social/
– BitBucket
● https://bitbucket.org/ → “Free Git tutorials”
– Gitorious
● https://gitorious.org/about/faq
https://github.com/danilobellini
Vejam meus projetos e falem
comigo caso queiram
colaborar em algum: