Contratos de licença de colaborador (CLAs)
Antes de aceitarmos seus patches de código, é necessário enviar um Contrato de Licença de Colaborador (CLA) individual ou corporativo:
- Se você for uma pessoa que escreveu o código-fonte original e tiver certeza de que é proprietário da propriedade intelectual, envie um CLA individual.
- Se você trabalha para uma empresa, ela precisa enviar um CLA corporativo para indicar que você tem permissão para contribuir com o trabalho nessa 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, podemos adicionar você à lista oficial de colaboradores.
Visão geral do envio de patches
Para contribuir com o código deste projeto, siga estas etapas gerais:
- Assine 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 seus conjuntos de mudanças a um problema (um relatório de bug ou solicitação de recurso) no nosso Issue Tracker do GitHub. Crie um novo problema, se ainda não houver um, e atribua-o a si mesmo.
- Confira o código, crie um novo problema em codereview.appspot.com e conclua o processo de revisão de código. Veja abaixo instruções detalhadas para todos esses processos.
- Depois que o código for revisado e você receber a aprovação, confirme o código. Se você não for um colaborador oficial, um colaborador poderá extrair seu conjunto de alterações 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 compilação, bem como para sistemas de distribuição binária.
- Usamos codereview.appspot.com para revisões de código. No entanto, na ferramenta codereview.appspot.com, o termo "issue" significa uma solicitação de revisão de código, enquanto, no Issue Tracker do GitHub, um "issue" é uma solicitação de recurso ou relatório de bug.
Se você é um desenvolvedor do Eclipse, use a formatação de código específica do projeto especificada no diretório .settings que é processado automaticamente pelo Eclipse.
Como configurar o ambiente de desenvolvimento
Pré-requisitos
- Instale o Java 6. Talvez seja necessário definir a variável
JAVA_HOME
. - Instale o Maven. Presumimos que você tenha familiaridade básica com os comandos do Maven.
- Opcional: instale o SDK do Android e defina a variável ANDROID_HOME para 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 usando o GitHub com o Git
Para verificar o código do GitHub, você precisa estar autenticado no GitHub usando HTTP ou SSH. Antes de prosseguir com as instruções abaixo, leia as instruções do GitHub (em inglês) para saber como começar a usar a clonagem de HTTPS ou SSH. Se você quiser saber mais sobre o Git em geral, consulte o Pro Git.
Conferir o código
Como usar HTTPS
Para conferir o repositório da biblioteca na ramificação de desenvolvimento "master" execute o seguinte comando:
git clone https://github.com/google/google-api-java-client.git
Como usar SSH
Para verificar o repositório da biblioteca na ramificação de desenvolvimento "master", verifique se você tem acesso de gravação ao repositório do GitHub e 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 a á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, será necessário instalar 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é o fim 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
Compile o projeto
mvn clean install
O Maven instala os binários compilados em um repositório local (por exemplo, ~/.m2/repository). Ele pesquisa binários nesse repositório antes de buscar no repositório Maven central.
Observação:esta biblioteca depende de google-http-java-client e de 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, você precisa 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 pegue os binários compilados para compilação de biblioteca dependente.
Processo de revisão de código
Como fazer o download do script upload.py
Faça o download do script upload.py e adicione-o ao seu PATH.
Na primeira vez que você executar upload.py
, ele solicitará 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 o 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 no código. Se algum erro for relatado, corrija-o ou atualize o arquivo clirr-ignored-differents.xml.
mvn -q clirr:check
Você também precisa executar a ferramenta FindBugs para detectar bugs no código. Se algum erro for relatado, corrija-o ou atualize o arquivo findfinds-exclude.xml. O FindBugs é muito lento.
mvn findbugs:check
Depois que a mudança for aprovada em todos os testes, acrescente ao índice (a área de preparo do Git):
git add .
Verifique 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 "Alterações a serem confirmadas."
Como iniciar a revisão de código
Quando estiver pronto para 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 alterações, prepare as novas alterações. Para fazer upload de um novo patch, por exemplo, para emitir o número 123456, execute o seguinte comando:
upload.py --rev=HEAD -i 123456
Para ver mais opções, execute upload.py --help
.
Se você preferir o fluxo de trabalho típico do GitHub, provavelmente 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 bifurcação, verifique se ela está sincronizada com o repositório upstream. Para mais informações, consulte a ajuda do GitHub sobre como sincronizar uma bifurcação.
Você também pode usar upload.py para conjuntos de alterações confirmadas localmente.
upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...
Revisor do código
Se você é um revisor de código, importe e teste o conjunto de alterações antes de aprová-lo. Em seguida, confirme e envie os conjuntos de dados ao repositório remoto.
Como importar um conjunto de alterações
Para detectar erros com antecedência, extraia as alterações mais recentes do repositório remoto na sua árvore de trabalho. Verifique se a árvore de trabalho está limpa e se o índice está vazio.
Para extrair e mesclar as últimas confirmações do repositório remoto:
git pull
Para verificar o que há na sua árvore de trabalho e no índice, faça o seguinte:
git status
Para importar um patch para seu clone do 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 "quot;raw"" para obter um URL do arquivo a ser importado.
- Salve o arquivo de diferença bruta na máquina local com um nome como issue123456.diff.
- Acesse a árvore de trabalho local do Git e aplique a comparação 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 o seguinte comando:
mvn clean install checkstyle:check
Como aprovar um conjunto de mudanças em codereview.appspot.com
Em geral, o código não pode ser enviado para o repositório do GitHub até que o revisor do código esteja satisfeito de que o código está pronto. Nesse ponto, a convenção é responder com a mensagem "LGTM" (Parece bom).
Como confirmar o código
Importante:antes de confirmar o código, extraia as alterações mais recentes na árvore de trabalho e atualize-a para a confirmação mais recente do repositório do GitHub:
git pull
Se houver conflitos, resolva-os e certifique-se de que todos os testes sejam 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 123, conforme listado no Issue Tracker do GitHub):
#123: NullPointerException when passing null to processFoo() http://codereview.appspot.com/123456/
Antes dos dois-pontos e da descrição:
- Se isso for uma correção para um problema no Issue Tracker, inclua o número do problema como mostrado.
- Se essa for uma alteração de uma ramificação específica, inclua o número dela.
- Você será o
committer
dessa confirmação, mas dê crédito ao autor da alteração marcando-a comoauthor
(--author=<author>
).
Após a descrição, sempre inclua um link para o problema no site de revisão de código. 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, siga estas etapas:
git push
Se durante o git push
você receber uma mensagem de erro sobre atualizações rejeitadas (talvez
você se esqueceu de executar git pull
), veja como se mesclar com as alterações mais recentes e
enviar suas alterações para o repositório remoto:
git pull git commit git push
Encerramento do 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 em "X" que fica no canto superior esquerdo, antes de "Id."
Como remover um conjunto de alterações
Se, por algum motivo, você decidir não confirmar um conjunto de alterações importado, use o comando a seguir para removê-lo. Cuidado: ela literalmente apaga todas as alterações locais.
git checkout -- .