Como colaborar

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:

  1. Assinar 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 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ê.
  5. 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.
  6. 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

  1. Instale o Java 6. Talvez seja necessário definir sua variável JAVA_HOME.
  2. Instale o Maven. Para seguir este documento, é necessário ter familiaridade com os comandos do Maven.
  3. Opcional: instale o SDK do Android e defina a variável ANDROID_HOME como 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 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:

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

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

  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 "raw" para acessar o URL do arquivo a ser importado.
  4. Salve o arquivo de diferenças brutas na máquina local com um nome, como issue123456.diff.
  5. 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 como author (--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:

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