Enviar mudanças no código

Esta página descreve o processo completo de envio de uma mudança no código para o Android Open Source Project (AOSP), incluindo como pedir uma revisão e monitorar as mudanças.

O AOSP depende do Gerrit, um sistema de análise de código baseado na Web para projetos que usam o Git.

Assinar os contratos de licença de colaborador

Antes de contribuir com qualquer mudança de código para AOSP, leia os Contratos de licença de colaborador e cabeçalhos e assine um destes contratos:

• Como contribuidor individual que faz contribuições apenas em seu nome, assine o Contrato de licença de colaborador individual.
• Como funcionário que trabalha para uma empresa, sua empresa precisa assinar o Contrato de licença de colaboração corporativa autorizando você a fazer contribuições em nome dela.

Observação: para mudar projetos upstream usados pelo Android, é necessário fazer isso diretamente no projeto. Para mais informações, confira Contribuir para projetos upstream.

Iniciar uma ramificação

Para cada mudança no código que você pretende fazer, siga estas etapas:

1. Inicie uma nova ramificação no repositório Git relevante. Uma ramificação não é uma cópia dos arquivos originais, mas sim um ponteiro para um commit específico, o que torna a criação de ramificações locais e a alternância entre elas uma operação leve. Ao usar ramificações, você pode identificar mudanças. Execute este comando para iniciar uma ramificação:

   repo start BRANCH_NAME

   É possível iniciar várias ramificações independentes ao mesmo tempo e no mesmo repositório. O BRANCH_NAME da ramificação é local em relação ao seu espaço de trabalho e não é incluído no Gerrit ou na árvore de origem final. As ramificações também são específicas do projeto em que você está, portanto, se precisar mudar arquivos em projetos diferentes como parte da mesma modificação, você precisará de uma ramificação em cada projeto onde você mudará os arquivos.

2. (opcional) Confira se a ramificação foi criada:

   repo status .

   Sua ramificação recém-criada vai aparecer. Por exemplo:

   project frameworks/native/                      branch mynewbranch

   Observação: você também pode usar repo branches para ver uma lista de todas as ramificações, com a ramificação atual (se houver) precedida por um asterisco (*).

Fazer e testar sua mudança

Siga estas etapas para fazer e testar sua mudança:

1. Para garantir que você está trabalhando com a base de código mais atual, execute uma sincronização de toda a base de código:

   repo sync

   Observação: para sincronizar apenas o projeto atual, adicione um ponto final (.) ao comando repo sync: repo sync .. Sincronizar o projeto atual é mais rápido que sincronizar todo o repositório.

   Se você tiver algum conflito durante a sincronização, consulte as etapas 2 a 4 em Resolver conflitos de sincronização.

2. Encontre o código que será modificado. Para encontrar o código, considere usar Android Code Search. Você pode usar o Android Code Search para visualizar o código-fonte do AOSP conforme ele é apresentado quando você o utiliza. Para mais informações, confira Começar a usar a pesquisa de código. Para visualizar todos os códigos na ramificação main no Android Code Search, navegue até https://cs.android.com/android/platform/superproject/main.

3. Modifique ou adicione arquivos de origem. Para qualquer mudança feita:

   • Determine se você precisa usar flags de lançamento de recursos e, caso necessário, implemente essas flags no novo código.

   • Siga as práticas recomendadas em Incluir cabeçalhos de licença.

   • Para o código Java, siga as orientações em Estilo de código Java do AOSP para colaboradores.

   • Algumas partes do AOSP são escritas em Kotlin (.kt), e você pode usar o Kotlin em áreas da plataforma que já estão escritas em Kotlin. Para mais informações sobre Kotlin no Android, consulte o Guia de estilo do Kotlin e o Guia de interoperabilidade entre Kotlin e Java para desenvolvedores Android. Para orientações mais abrangentes sobre Kotlin, consulte o site da linguagem Kotlin (em inglês).

   • Ao escrever APIs, siga as diretrizes da API Android. Use essas diretrizes para saber o contexto por trás das decisões de API do Android. As adições e modificações das APIs da plataforma são validadas pela Metalava.

4. Criar para o Android

5. Testar seu build.

Organizar e fazer commit da sua mudança

Um commit é a unidade básica do controle de revisão no Git e consiste em um snapshot da estrutura do diretório e no conteúdo do arquivo para todo o projeto. Siga estas etapas para confirmar a mudança:

1. Por padrão, o Git registra, mas não monitora, as mudanças feitas. Para instruir o Git a rastrear suas mudanças, você deve marcar ou organizar essas mudanças para inclusão em um commit. Execute este comando para organizar a mudança:

   git add -A

   Este comando rastreia as mudanças feitas em qualquer arquivo.

   Observação: se você só quer rastrear mudanças em um arquivo específico, use git add filename.
   Observação: além de rastrear mudanças em arquivos, git add pode ser usado para executar outras operações, como organizar modificações e exclusões de arquivos.

2. Pegue os arquivos na área de teste e envie-os ou armazene-os em sua base de dados local:

   git commit -s

   Por padrão, um editor de texto é aberto e você precisará fornecer uma mensagem de commit.

3. Digite a mensagem neste formato:

   • Linha 1: título. Forneça um resumo de uma linha da mudança (máximo de 50 caracteres). Recomendamos o uso de prefixos para descrever a área que você mudou, seguidos por uma descrição da mudança feita nesse commit, como o exemplo abaixo contendo uma mudança na interface do usuário:

     ui: Removes deprecated widget
     

   • Linha 2: linha em branco. Siga o título com uma linha em branco.

   • Linha 3: corpo. Forneça uma descrição longa com no máximo 72 caracteres. Descreva o problema que a mudança resolve e como a solução funciona. Embora o corpo seja opcional, ele é útil para outras pessoas que precisam consultar a mudança. Inclua uma breve explicação das suposições ou informações contextuais que possam ser importantes quando outro colaborador trabalhar nesse recurso.

   Para saber mais sobre boas descrições de commits (com exemplos), consulte a postagem de blog Como escrever uma mensagem de confirmação do Git (em inglês).

4. Salve o commit.

Um código de mudança exclusivo e seu nome e e-mail, que foram fornecidos durante a repo init (inicialização do Repo), são automaticamente adicionados à sua mensagem de commit.

Fazer upload da mudança para revisão

Depois de fazer o commit da mudança para seu histórico pessoal do Git, faça upload dela para o Gerrit:

1. Execute o comando abaixo para fazer upload de todos os commits em todos os seus projetos:

   repo upload

   Todas as mudanças feitas em todos os projetos estão incluídas no upload.

   Observação: para fazer upload de mudanças apenas no projeto atual, adicione um ponto (.) ao comando repo upload: repo upload ..
   Observação: se você estiver trabalhando em uma mudança que exija modificações nos arquivos em vários projetos, use um tópico no Gerrit para uni-las independente do uso de repo upload ou repo upload .. O tema do Gerrit garante que as mudanças sejam mantidas juntas para fins de pré-envio de testes e pela mesclagem automática. Para mais informações, consulte Como usar temas

   Você precisará executar scripts de hook.

2. Pressione a tecla a e, em seguida, Enter.

   Será necessário aprovar o upload:

   Upload project frameworks/native/ to remote branch main:
   branch BRANCH_NAME ( 1 commit, Wed Aug 7 09:32:33 2019 -0700):
          ff46b36d android codelab change
   to https://android-review.googlesource.com/ (y/N)?
   

   Observação: se você iniciou várias ramificações no mesmo repositório, vai precisar selecionar quais enviar, removendo a marca de comentário dessas ramificações no seu editor de texto.

3. Pressione a tecla y e, em seguida, Enter para aprovar o upload.

Você receberá uma mensagem semelhante a esta: remote: SUCCESS.

Pedir uma revisão

Após a conclusão do upload, o Repo fornecerá um link para suas mudanças no Gerrit. Clique no link para visualizar as mudanças no servidor de revisão, adicionar comentários, ou pedir por revisores específicos para a modificação. Todas as mudanças no código precisam ser revisadas pelos proprietários do código apropriados. Para pedir uma revisão, siga estas etapas:

1. No Gerrit, clique em SUGGEST OWNERS:

   

   Figura 1. Link "Suggest owners" no Gerrit.

   A caixa de diálogo do revisor é mostrada. Ela contém uma lista de proprietários de código que podem revisar a mudança.

2. Clique em um proprietário do código para adicioná-lo à revisão.

   Observação: para entender como os proprietários são determinados, consulte o backend find-owners.

   O botão SEND (enviar) será ativado.

3. (Opcional) Insira o endereço de e-mail das pessoas que você gostaria que revisassem a mudança.

4. (Opcional) Clique em +1 ao lado de "Autosubmit" (Envio automático) para enviar a mudança automaticamente depois de receber aprovação. Se você não clicar nesse botão, um funcionário do Google terá que enviar a mudança para você.

5. Clique em SEND para enviar as mudanças para revisão.

Os proprietários do código revisam as mudanças e fornecem feedback para você resolver ou aprovam as modificações.

Determinar status da mudança

Para determinar o status dos arquivos na mudança, consulte estes ícones ao lado dela:

• (ícone de verificação): aprovado pelo proprietário do código.
• (ícone de X): não aprovado pelo proprietário do código.
• (ícone de relógio): aprovação pendente.

A figura abaixo mostra esses ícones de status aplicados aos arquivos em uma mudança:

Figura 2. Exemplo de arquivos com ícones que mostram a aprovação do proprietário do código.

Resolver feedback e fazer upload de uma mudança de substituição

Se um avaliador pedir que uma modificação seja feita na sua atualização, você pode mudar seu commit no Git, o que resulta em um novo conjunto de patches na mesma mudança.

Observação: se você criou outras ramificações e fez outros commits depois do upload de uma mudança, provavelmente estará trabalhando na ramificação para um desses commits e não a ramificação da mudança original. Então, antes de resolver o feedback para a ramificação original, é necessário navegar até essa ramificação usando o comando repo start EXISTING_BRANCH_NAME (link em inglês).

Para resolver comentários e ajustar a mudança:

1. Siga as etapas 2 a 4 em Fazer e testar sua mudança.

2. Execute estes comandos para alterar a mudança:

   git add -A
   git commit --amend

3. Faça upload da sua mudança

Quando você fizer upload da mudança, ela substituirá a original no Gerrit e no histórico do Git local.

Resolver conflitos de sincronização

Se outras mudanças forem enviadas à árvore de origem que entrem em conflito com a sua, você receberá uma mensagem de aviso. Para resolver os conflitos:

1. Para garantir que você está usando o código mais atual:

   repo sync .

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

2. Se a realocação automática não for bem-sucedida, faça uma manual:

   repo rebase .

3. Resolva conflitos de mesclagem. Se você não tiver um método preferido para resolver conflitos de mesclagem, use git mergetool (link em inglês) para corrigir conflitos entre arquivos manualmente.

4. Depois de corrigir os arquivos conflitantes, execute este comando para aplicar os novos commits:

   git rebase --continue

Enviar mudança

Depois que um envio passa pelo processo de revisão e verificação, um avaliador do Google vai enviar o código para você. Outros usuários podem executar repo sync para transferir a atualização para os próprios clientes locais.

Depois que seu envio for mesclado, você poderá acessar o painel Integração contínua do Android para acompanhar quando seus envios forem integrados à árvore.