Como enviar patches

Esta página descreve o processo completo de envio de um patch para o AOSP, incluindo revisão e controle de alterações com o Gerrit.

Pré-requisitos

Para colaboradores

Autenticar com o servidor

Antes de fazer upload para o Gerrit, você precisa definir uma senha que o identifique junto ao servidor. Siga as instruções na página do gerador de senhas. É necessário fazer isso apenas uma vez. Consulte Como usar a autenticação para ver mais detalhes.

Iniciar um branch do repo

Para cada alteração que você pretende fazer, inicie um novo branch dentro do repositório git relevante:

repo start NAME .

É possível iniciar vários branches independentes ao mesmo tempo e no mesmo repositório. O branch NAME é local em relação ao seu espaço de trabalho e não será incluído no Gerrit ou na árvore de origem final.

Fazer a alteração

Depois de modificar os arquivos de origem (e validá-los) confirme as alterações no seu repositório local:

git add -A
git commit -s

Forneça uma descrição detalhada da alteração na sua mensagem de confirmação. Essa descrição será enviada para o repositório AOSP público, então siga nossas diretrizes para escrever as descrições da lista de alterações:

  • Comece com um resumo de apenas uma linha (máximo de 50 caracteres), seguido por uma linha em branco. Esse formato é usado pelo git e Gerrit para várias exibições.

  • A partir da terceira linha, insira uma descrição mais longa, que precisa ser limitada ao tamanho máximo de 72 caracteres. Essa descrição precisa se concentrar no problema que a alteração resolve e em como ela o resolve. A segunda parte é, de certa forma, opcional na implementação de novos recursos, embora seja desejável.

  • Inclua uma breve observação das suposições ou informações básicas que possam ser importantes quando outro colaborador trabalhar nesse recurso no ano seguinte.

Este é um exemplo de uma mensagem de confirmação:

short description on first line

more detailed description of your patch,
which is likely to take up multiple lines.

Uma código de alteração exclusivo, seu nome e e-mail fornecidos durante o repo init serão automaticamente adicionados à sua mensagem de confirmação.

Upload para Gerrit

Depois de ter confirmado a alteração do seu histórico pessoal, envie-a para o Gerrit com

repo upload

Se você iniciou vários branches no mesmo repositório, terá que selecionar qual será enviado por upload.

Após um upload bem-sucedido, o repo fornecerá o URL de uma nova página no Gerrit. Acesse esse link para ver seu patch no servidor de análise, adicionar comentários ou solicitar revisores específicos para seu patch.

Como fazer upload de um patch substituto

Suponha que um revisor analisou seu patch e solicitou uma pequena modificação. Você pode alterar sua confirmação no git, o que resultará em um novo patch no Gerrit com o mesmo código de alteração que o original.

git add -A
git commit --amend

Quando você fizer upload do patch corrigido, ele substituirá o original no Gerrit e no histórico do git local.

Como resolver conflitos de sincronização

Se outros patches enviados para a árvore de origem entrarem em conflito com o seu, você precisará realocar seu patch sobre o novo HEAD do repositório de origem. A maneira mais fácil de fazer isso é executar

repo sync

Esse comando busca primeiro as atualizações do servidor de origem e, em seguida, tenta realocar seu HEAD automaticamente no novo HEAD remoto.

Se a realocação automática não for bem sucedida, será necessário realizar uma realocação manual.

repo rebase

Usar o git mergetool pode ajudar você a lidar com o conflito de realocação. Depois de ter mesclado os arquivos conflitantes,

git rebase --continue

Depois que a realocação automática ou manual for concluída, execute repo upload para enviar o patch realocado.

Após a aprovação de um envio

Depois que um envio passa pelo processo de análise e verificação, o Gerrit mescla automaticamente a alteração no repositório público. Outros usuários poderão executar repo sync para transferir a atualização para o cliente local deles.

Projetos ascendentes

O Android usa diversos outros projetos de código aberto, como o kernel do Linux e o WebKit, conforme descrito em Linhas de código, branches e versões. Para a maioria dos projetos em external/, as alterações precisam ser feitas de forma ascendente e, em seguida, os administradores do Android são informados da nova versão ascendente que contém essas alterações. Também pode ser útil fazer upload de patches que nos levem a rastrear uma nova versão ascendente, embora essas possam ser alterações difíceis de realizar se o projeto for amplamente usado no Android, como a maioria das grandes alterações mencionadas abaixo, onde a tendência é que o upgrade seja feito a cada versão.

Um caso especial interessante é o bionic. Grande parte do código dele vem do BSD, por isso, a menos que a alteração seja realizada no código que é novo no bionic, é preferível ter uma correção ascendente para então extrair um novo arquivo completo do BSD apropriado. Infelizmente, há uma grande mistura de BSDs diferentes no momento, mas esperamos resolver isso no futuro e chegar a um ponto em que seja possível rastrear projetos ascendentes de forma mais atenta.

ICU4C

Todas as alterações do projeto ICU4C em external/icu4c precisam ser realizadas de forma ascendente em icu-project.org/. Consulte Como enviar solicitações de recursos e bugs de ICU (em inglês) para ver mais informações.

LLVM/Clang/Compiler-rt

Todas as alterações em projetos relacionados a LLVM (external/clang, external/compiler-rt, external/llvm) precisam ser feitas de forma ascendente em llvm.org/.

mksh

Todas as alterações no projeto do MirBSD Korn Shell em external/mksh precisam ser feitas de forma ascendente enviando um e-mail para miros-mksh no domínio mirbsd.org (não é necessário ter uma assinatura para realizar o envio) ou no Launchpad.

OpenSSL

Todas as alterações no projeto OpenSSL em external/openssl precisam ser realizadas de forma ascendente em openssl.org.

V8

Todas as alterações no projeto V8 em external/v8 precisam ser enviadas de forma ascendente em code.google.com/p/v8. Consulte Como contribuir com o V8 (em inglês) para ver mais detalhes.

WebKit

Todas as alterações no projeto WebKit em external/webkit precisam ser realizadas de forma ascendente em webkit.org. O processo começa com o registro de um bug do WebKit. Esse bug usará o Android para os campos Platform e OS somente se o bug for específico do Android. É muito mais provável que os bugs recebam atenção dos revisores quando uma correção proposta for adicionada e os testes forem incluídos. Consulte Como contribuir com código para o WebKit (em inglês) para ver mais detalhes.

zlib

Todas as alterações do projeto zlib em external/zlib precisam ser feitas de forma ascendente em zlib.net.