Como colaborar

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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:

  1. Assine um Contrato de Licença de Colaborador, conforme descrito acima.
  2. Participe do nosso grupo de discussão.
  3. Configure seu ambiente de desenvolvimento.
  4. 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.
  5. 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.
  6. 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

  1. Instale o Java 6. Talvez seja necessário definir a variável JAVA_HOME.
  2. Instale o Maven. Presumimos que você tenha familiaridade básica com os comandos do Maven.
  3. Opcional: instale o SDK do Android e defina a variável ANDROID_HOME para o local de instalação do Android.
  4. 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:

  1. Inicie o Eclipse e selecione Window > Android SDK Manager ou execute android na linha de comando.
  2. 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:

  1. google-http-java-client
  2. google-oauth-java-client
  3. 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:

  1. Abra o problema em codereview.appspot.com.
  2. Para o patch em questão, procure "Download bruto" no canto superior direito da especificação do patch.
  3. Clique em "quot;raw"" para obter um URL do arquivo a ser importado.
  4. Salve o arquivo de diferença bruta na máquina local com um nome como issue123456.diff.
  5. 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 como author (--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:

  1. Selecione o problema em codereview.appspot.com.
  2. 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 -- .