Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos Open Source, como colaborar? – 2015-03-14

ProjetosProjetosOpen Source,Open Source,

Como colaborar?Como colaborar?

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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, ...

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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● ...

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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/bugs/?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!

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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/exploreTra

duções?

EVENTOS! Agitar a galera!

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos Open Source, como colaborar? – 2015-03-14

É É preciso preciso ver aos ver aos poucos!poucos!

GitControle 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 todas Insere 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ão Exibe 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/

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos Open Source, como colaborar? – 2015-03-14

GUI para o git?

gitk

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos Open Source, como colaborar? – 2015-03-14

GitHubHospedagem 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

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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)

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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.

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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?

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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.

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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?

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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...

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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

Danilo J. S. Bellini – @danilobellini – São Paulo – SPProjetos 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: