Contratos de Licença de Colaboração (CLAs, na sigla em inglês)
Antes de aceitarmos seus patches de código, você precisa enviar um Contrato de Licença de Colaborador (CLA, na sigla em inglês) corporativo ou individual:
- Se você é uma pessoa que escreve um código-fonte original e tem certeza de que é o proprietário da propriedade intelectual, envie um CLA individual.
- Se você trabalha em uma empresa, ela precisa enviar um CLA corporativo para indicar que você tem permissão para contribuir com essa biblioteca de cliente.
Por um dos dois links acima, acesse o CLA adequado e as instruções sobre como assiná-lo e retorná-lo. Assim que recebermos o documento, poderemos adicionar você à lista oficial de colaboradores.
Visão geral do envio de patches
Para contribuir com código para este projeto, siga estas etapas gerais:
- Assinar um Contrato de Licença de Colaborador, conforme descrito acima.
- Participe do nosso grupo de discussão.
- Configure seu ambiente de desenvolvimento.
- Associe cada um dos conjuntos de mudanças a um problema (um relatório de bug ou uma solicitação de recurso) no Issue Tracker do GitHub. Crie um novo problema, se ainda não houver, e o atribua a você.
- Confira o código, crie um novo problema em codereview.appspot.com e conclua o processo de revisão de código. Instruções detalhadas para todos esses processos são fornecidas abaixo.
- Confirme o código depois que ele for analisado e você receber aprovação. Se você não for um Colaborador oficial, um Colaborador vai extrair seu conjunto de mudanças no repositório oficial.
Usamos as seguintes ferramentas e processos:
- Usamos o Git como nosso sistema de controle de versões.
- Usamos o Maven para o sistema de build e um sistema de distribuição binária.
- Usamos codereview.appspot.com para revisões de código. No entanto, na ferramenta codereview.appspot.com, o termo "problema" significa uma solicitação de revisão de código, enquanto no Issue Tracker do GitHub, um "problema" é uma solicitação de recurso ou relatório de bug.
Se você é desenvolvedor do Eclipse, use a formatação de código específica do projeto no diretório .settings processado automaticamente pelo Eclipse.
Como configurar o ambiente de desenvolvimento
Pré-requisitos
- Instale o Java 6. Talvez seja necessário definir sua variável
JAVA_HOME
. - Instale o Maven. Para seguir este documento, é necessário ter familiaridade com os comandos do Maven.
- Opcional: instale o SDK do Android e defina a variável ANDROID_HOME como o local de instalação do Android.
- Instale o Git.
Como configurar o Git
Use o comando git config
para definir o nome de exibição e o endereço de e-mail padrão:
git config --global user.name "YOUR NAME" git config --global user.email "YOUR EMAIL ADDRESS"
Como autenticar com o GitHub usando o Git
Para verificar o código do GitHub, você precisa estar autenticado com o GitHub usando HTTP ou SSH. Antes de continuar seguindo as instruções abaixo, leia as instructions do GitHub sobre como começar a usar a clonagem de HTTPS ou SSH. Se você quiser saber mais sobre o Git em geral, o Pro Git é um bom recurso.
Como conferir o código
Como usar HTTPS
Para verificar o repositório da biblioteca na ramificação "master" de desenvolvimento, execute o seguinte comando:
git clone https://github.com/google/google-api-java-client.git
Como usar SSH
Para conferir o repositório da biblioteca na ramificação "mestre" de desenvolvimento, verifique se você tem acesso de gravação no repositório do GitHub. Em seguida, execute o seguinte comando:
git clone git@github.com:google/google-api-java-client.git
Para alternar para uma ramificação alternativa, por exemplo, 1.12:
git checkout --track origin/1.12
Para voltar para a ramificação mestre:
git checkout master
Para receber as alterações mais recentes do repositório do GitHub e atualizar sua árvore de trabalho local para a confirmação mais recente:
git pull
Maven
Instalar o Google Play Services
Na primeira vez que você configurar o projeto, instale o arquivo google-play-services.jar. Para isso, siga estas etapas:
- Inicie o Eclipse e selecione Window > Android SDK Manager ou execute
android
na linha de comando. - Role até a parte de baixo da lista de pacotes e selecione Extras > Google Play Services.
mvn install:install-file \ -Dfile=$ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar \ -DgroupId=com.google.android.google-play-services \ -DartifactId=google-play-services \ -Dversion=1 \ -Dpackaging=jar
Compilar o projeto
mvn clean install
O Maven instala os binários compilados em um repositório local (por exemplo, ~/.m2/repository). Ela procura binários nesse repositório antes de buscar no repositório central do Maven.
Observação: essa biblioteca depende de google-http-java-client e google-oauth-java-client. Ao trabalhar em uma nova versão das três bibliotecas que ainda não foram lançadas no Maven central, é preciso compilá-las na seguinte ordem:
- google-http-java-client
- google-oauth-java-client
- google-api-java-client A compilação nessa ordem garante que o Maven capture os binários compilados para compilação de biblioteca dependente.
Processo de revisão de código
Download do script upload.py
Faça o download do script upload.py e, se quiser, adicione-o ao seu PATH.
Na primeira vez que você executa upload.py
, ele pede uma
senha específica do aplicativo:
Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com Password for your_email_address@yourdomain.com:
Como preparar seu código para revisão
Antes de enviar o código para revisão, execute o Clirr para detectar problemas de compatibilidade com versões anteriores. Se algum erro for informado, será necessário corrigi-lo ou atualizar o arquivo clirr-ignored-differences.xml.
mvn -q clirr:check
Você também precisa executar a ferramenta FindBugs para detectar bugs no código. Se algum erro for informado, será necessário corrigi-lo ou atualizar o arquivo findbugs-excluded.xml. O FindBugs é muito lento.
mvn findbugs:check
Depois que a mudança for aprovada em todos os testes, adicione a mudança ao índice (a área de teste do Git):
git add .
Verifique novamente se todos os arquivos adicionados, modificados ou excluídos são refletidos no índice:
git status
Na saída git status
, verifique a seção chamada "Mudanças a serem confirmadas".
Como iniciar a revisão de código
Quando estiver tudo pronto para a revisão, crie um novo problema em codereview.appspot.com:
upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...
Depois de fazer mais mudanças, prepare as novas. Para fazer upload de um novo patch, por exemplo, para o número de emissão 123456, execute o seguinte comando:
upload.py --rev=HEAD -i 123456
Para mais opções, execute upload.py --help
.
Se você prefere o fluxo de trabalho do GitHub típico, provavelmente já bifurcou o repositório do GitHub e criou uma ramificação para esse novo recurso ou correção de bug. Ao enviar solicitações de revisão de código da sua própria bifurcação, verifique se ela está sincronizada com o repositório upstream. Para saber mais, consulte a ajuda do GitHub sobre como sincronizar uma bifurcação.
Também é possível usar upload.py para conjuntos de alterações confirmados localmente.
upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...
Revisor de código
Se você for um revisor de código, importe e teste os conjuntos de alterações antes de aprová-los. Em seguida, confirme e envie os conjuntos de alterações para o repositório remoto.
Importar um conjunto de mudanças
Para detectar erros antecipadamente, extraia as alterações mais recentes do repositório remoto para a árvore de trabalho. Verifique se a árvore de trabalho está limpa e o índice vazio.
Para efetuar pull e mesclar as confirmações mais recentes do repositório remoto:
git pull
Para verificar o que está na árvore e no índice de trabalho:
git status
Para importar um patch para seu clone Git local:
- Abra o problema em codereview.appspot.com.
- Para o patch em questão, procure "Download bruto" no canto superior direito da especificação do patch.
- Clique em "raw" para acessar o URL do arquivo a ser importado.
- Salve o arquivo de diferenças brutas na máquina local com um nome, como issue123456.diff.
- Acesse a árvore de trabalho local do Git e aplique a diferença usando o
comando
patch
:
patch -p1 < issue123456.diff
Para verificar novamente se você importou a diferença correta, faça um git diff
na árvore de trabalho.
Como testar o conjunto de mudanças
Para executar os testes e instalar, use este comando:
mvn clean install checkstyle:check
Aprovando um conjunto de alterações em codereview.appspot.com
Em geral, o código não pode ser enviado por push para o repositório do GitHub até que o revisor de código confirme que o código está pronto. Nesse momento, a convenção é responder com a mensagem "LGTM" ("Looks Good To Me").
Confirmação do código
Importante:antes de confirmar o código, extraia as mudanças mais recentes na árvore de trabalho e a atualize para a confirmação mais recente do repositório do GitHub:
git pull
Se houver conflitos, resolva-os e verifique se todos os testes são aprovados novamente.
Para confirmar o código localmente:
git commit
Insira uma mensagem como a seguinte (supondo que você esteja corrigindo ou implementando o problema no 123, conforme listado no Issue Tracker do GitHub):
#123: NullPointerException when passing null to processFoo() http://codereview.appspot.com/123456/
Antes dos primeiros dois-pontos e da descrição:
- Se isso for a correção de um problema no Issue Tracker, inclua o número dele, conforme mostrado.
- Se esta for uma mudança de uma ramificação específica, inclua o número dela.
- Você será o
committer
desta confirmação, mas dê crédito ao autor da alteração marcando-o comoauthor
(--author=<author>
).
Após a descrição, sempre inclua um link para o problema no site do codereview. Esse link é importante porque, sem ele, não há uma maneira conveniente de descobrir a revisão de código associada a uma confirmação, o que é útil para manter um histórico da discussão.
Para enviar a alteração ao repositório do GitHub:
git push
Se, durante git push
, você receber uma mensagem de erro sobre a rejeição de atualizações (talvez
tenha esquecido de executar git pull
), veja como mesclar com as mudanças mais recentes e
enviar as alterações ao repositório remoto:
git pull git commit git push
Encerrar o problema
Feche o problema na ferramenta de revisão de código. Para isso, siga estas etapas:
- Selecione o problema em codereview.appspot.com.
- Clique no "X" que está no canto superior esquerdo, antes de "Id".
Como despachar um conjunto de mudanças
Se, por algum motivo, você decidir não confirmar um conjunto de mudanças importado, use o comando a seguir para eliminá-lo. Cuidado: ele apaga todas as mudanças locais.
git checkout -- .