Como colaborar

Contratos de licença de colaborador (CLAs, na sigla em inglês)

Antes de aceitarmos seus patches de código, você precisa enviar uma versão ou um Contrato de licença de colaborador (CLA, na sigla em inglês) corporativo:

  • Se você escreve código-fonte original e tem certeza de que você é o proprietário da propriedade intelectual, envie uma CLA individual.
  • Se você trabalha para uma empresa, ela precisa enviar um CLA corporativo. para indicar que você tem permissão para contribuir com seu trabalho para 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 o recebermos, 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. Assine um Contrato de Licença de Colaborador, conforme descrito acima.
  2. Participe do nosso grupo de discussão.
  3. Configure o ambiente de desenvolvimento.
  4. Associar cada um dos seus conjuntos de alterações a um problema (um relatório de bug ou recurso ) em nosso 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 revisado e aprovado. Se você não for um colaborador oficial, ele vai enviar seu conjunto de mudanças para o repositório oficial.

Usamos as seguintes ferramentas e processos:

  • Usamos o Git como nosso sistema de controle de versões.
  • Para o sistema de build, usamos o Maven, um sistema de distribuição binária.
  • Usamos codereview.appspot.com para o código avaliações. Observe que, na ferramenta codereview.appspot.com, o termo "issue" significa uma solicitação de análise de código, enquanto no Issue Tracker do GitHub, um "problema" é um solicitação de recurso ou relatório do 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 seu JAVA_HOME variável.
  2. Instale o Maven. (Este documento pressupõe que você tenha familiaridade básica com os comandos do Maven.
  3. Opcional: instalar 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 a partir do Git

Para conferir o código do GitHub, você precisa ser autenticado com o GitHub usando HTTP ou SSH. Antes de continuar as instruções abaixo, leia a documentação instruções sobre como receber começaram com a clonagem de HTTPS ou SSH. Se você quiser saber mais sobre o Git na no geral, o Pro Git é um bom recurso.

Conferindo o código

Como usar HTTPS

Para verificar o repositório da biblioteca no "mestre" de desenvolvimento galho, 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 no "mestre" de desenvolvimento ramificação, fazer claro tenha 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 mudar 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 extrair as alterações mais recentes do repositório GitHub e atualizar seu local árvore de trabalho para o commit mais recente:

git pull

Maven

Instalar o Google Play Services

Na primeira vez que você configurar o projeto, será preciso instalar o google-play-services.jar. Para fazer isso:

  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 e serviços.
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 os binários no repositório antes de buscar do repositório Maven central.

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 foi lançada para o Maven central, precisam ser compilados 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 colete os binários compilados para compilação de bibliotecas 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, opcionalmente, adicioná-lo ao seu PATH.

Na primeira vez que você executa o 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 recuperar problemas de compatibilidade no código. Se algum erro for informado, corrigi-los 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 houver erros for relatado, será necessário corrigi-los ou atualizar o arquivo findbugs-exclude.xml . O FindBugs é muito lento.

mvn findbugs:check

Depois que sua alteração for aprovada em todos os testes, adicione-a ao índice (a fase de preparação área):

git add .

Confira se todos os arquivos que você adicionou, modificou ou excluiu estão refletidos. no índice:

git status

No resultado de git status, verifique a seção chamada "Changes to be commit".

Como iniciar a revisão de código

Quando estiver pronto para análise, 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, organize as novas. Para fazer upload de um novo patch, faça o seguinte: Por exemplo, para emitir o número 123456, execute o seguinte comando: 

upload.py --rev=HEAD -i 123456

Para mais opções, execute upload.py --help.

Se você preferir a versão comum do GitHub fluxo de trabalho, você provavelmente bifurcou o repositório do GitHub e criamos uma ramificação para esse novo recurso ou correção de bug. Quando você enviar código analisar solicitações da sua própria bifurcação, verificar se ela está em sincronia 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 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 conjuntos de alterações antes de aprová-los, Em seguida, faça commit e envie os conjuntos de alterações para o repositório remoto.

Como importar um conjunto de alterações

Para detectar erros com antecedência, certifique-se de extrair as alterações mais recentes do controle remoto repositório em sua árvore de trabalho. Certifique-se de que sua árvore de trabalho esteja limpa e seu índice estiver vazio.

Para extrair e mesclar as confirmações mais recentes do repositório remoto:

git pull

Para verificar o que está na sua árvore de trabalho e no seu índice:

git status

Para importar um patch para o seu clone do Git local:

  1. Abra o problema em codereview.appspot.com.
  2. Para o patch em questão, procure "Fazer o download do arquivo bruto" no canto superior direito especificação de patch.
  3. Clique em "bruto". para gerar um URL do arquivo que será importado.
  4. Salve o arquivo de diferença bruto na sua máquina local com um nome como issue123456.diff.
  5. Acesse sua árvore de trabalho do Git local e aplique a comparação usando o patch comando:
patch -p1 < issue123456.diff

Para verificar novamente se você importou a diferença correta, execute git diff em sua á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

Aprovação de um conjunto de alterações em codereview.appspot.com

Em geral, o código não pode ser enviado para o repositório do GitHub até que o revisor de código estiver satisfeito com o código pronto. Nesse caso, a convenção é responder com a mensagem "LGTM" (Tudo certo para mim).

Como confirmar o código

Importante: antes de confirmar seu código, extraia as alterações mais recentes em seu árvore de trabalho e atualizar sua árvore de trabalho para a confirmação mais recente do GitHub repositório:

git pull

Se houver conflitos, resolva-os e faça todos os testes passar de novo.

Para confirmar o código localmente: 

git commit

Insira uma mensagem como a seguinte (supondo que você esteja corrigindo ou implementando Problema 123, conforme listado no GitHub Issue Tracker):

#123: NullPointerException when passing null to processFoo()
http://codereview.appspot.com/123456/

Antes dos primeiros dois-pontos e da descrição:

  • Se isso for uma correção para um problema no Issue Tracker, inclua o número dele, conforme mostrado.
  • Se for uma mudança para uma ramificação específica, inclua o número dela.
  • Você será o committer deste compromisso, mas dê crédito ao autor da mudança marcando-o como o author (--author=<author>).

Seguindo a descrição, sempre inclua um link para o problema na revisão de código site. Esse link é importante porque, sem ele, não há uma maneira conveniente de descobrir a revisão de código associada a um commit, o que é útil para e manter um histórico da discussão.

Para enviar a alteração por push ao repositório do GitHub:

git push

Se durante o git push você receber uma mensagem de erro sobre a rejeição de atualizações (talvez você esqueceu de executar git pull), veja como mesclar com as alterações mais recentes e envie as alterações para o repositório remoto: 

git pull
git commit
git push

Encerrar o problema

Feche o problema na ferramenta de revisão de código. Para fazer isso:

  1. Selecione o problema em codereview.appspot.com.
  2. Clique no "X" que está no canto superior esquerdo, precedendo "Id".

Remoção de patch de 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 se livrar dele. Cuidado: ele literalmente apaga todas as mudanças locais. 

git checkout -- .