Invia modifiche al codice

In questa pagina viene descritta la procedura completa per inviare una modifica del codice ad Android Open Source Project (AOSP), incluso come richiedere una revisione e monitorare le modifiche.

AOSP si basa su Gerrit, un sistema di revisione del codice basato sul web per i progetti che utilizzano Git.

Firmare i contratti di licenza per i collaboratori

Prima di contribuire con eventuali modifiche al codice per AOSP, devi leggere le intestazioni e i contratti di licenza di Collaboratori e firmare uno dei seguenti contratti:

• In qualità di singolo collaboratore che apporta contributi solo per tuo conto, firma il Contratto di licenza per collaboratori individuali.
• In qualità di dipendente che lavora per una società, assicurati che la tua azienda abbia firmato il Contratto di licenza per i collaboratori aziendali che ti autorizza a fornire contributi per suo conto.

Avvia un ramo

Per ogni modifica che intendi apportare al codice, segui questi passaggi:

1. Avviare un nuovo ramo all'interno del repository Git pertinente. Un ramo non è una copia dei file originali, ma è un puntatore a un commit specifico, il che rende la creazione di rami locali e il passaggio da uno all'altro un'operazione leggera. Utilizzando i rami, puoi identificare le modifiche reciproche. Esegui questo comando per avviare un ramo:

   repo start BRANCH_NAME
   

   Puoi avviare più rami indipendenti contemporaneamente nello stesso repository. Il ramo BRANCH_NAME è locale della tua area di lavoro e non è incluso né in Gerrit né nell'albero di origine finale. I rami sono specifici del progetto in cui ti trovi, quindi se devi modificare i file di progetti diversi nell'ambito della stessa modifica, avrai bisogno di un ramo in ogni progetto in cui modifichi i file.

2. (Facoltativo) Verifica che il ramo sia stato creato:

   repo status .
   

   Dovresti vedere il ramo appena creato. Ecco alcuni esempi:

   project frameworks/native/                      branch mynewbranch
   

Apportare e testare la modifica

Per apportare e testare la modifica:

1. Per assicurarti di lavorare con il codebase più recente, esegui una sincronizzazione dell'intero codebase:

   repo sync
   

   In caso di conflitti durante la sincronizzazione, fai riferimento ai passaggi 2-4 della sezione Risolvere i conflitti di sincronizzazione.

2. Cerca il codice da modificare. Per trovare il codice, valuta la possibilità di utilizzare Ricerca Codice di Android. Puoi utilizzare Ricerca Codice di Android per visualizzare il codice sorgente AOSP così come è strutturato quando viene effettivamente utilizzato. Per ulteriori informazioni, consulta la Guida introduttiva a Ricerca Codice. Per visualizzare tutto il codice nella filiale main all'interno della ricerca di codici Android, vai a https://cs.android.com/android/platform/superproject/main.

3. Modifica o aggiungi file di origine. Per le modifiche apportate:

   • Segui le best practice in Includere le intestazioni delle licenze.

   • Per il codice Java, segui lo stile del codice Java AOSP per i collaboratori.

   • Alcune parti dell'AOSP sono scritte in Kotlin (.kt) e puoi utilizzarlo nelle aree della piattaforma già scritte in Kotlin. Per ulteriori informazioni su Kotlin in Android, consulta la guida di stile di Kotlin per sviluppatori Android e la guida all'interoperabilità di Kotlin-Java. Per indicazioni più dettagliate su Kotlin, visita il sito su Kotlin.

   • Quando scrivi le API, segui le linee guida delle API Android. Utilizza queste linee guida per esaminare il contesto alla base delle decisioni relative alle API di Android. Aggiunte e modifiche delle API della piattaforma vengono convalidate da Metalava.

4. Crea Android.

5. Testa la build.

Staging ed esegui il commit della modifica

Un commit è l'unità di base del controllo della revisione in Git ed è costituito da uno snapshot della struttura di directory e dei contenuti dei file per l'intero progetto. Per eseguire il commit della modifica, segui questi passaggi:

1. Per impostazione predefinita, Git registra le modifiche che apporti, ma non tiene traccia. Per indicare a Git di monitorare le modifiche, devi contrassegnare o temporaneamente le modifiche per l'inclusione in un commit. Esegui questo comando per posizionare temporaneamente la modifica:

   git add -A
   

   Questo comando monitora le modifiche apportate ai file.

2. Prendi i file nell'area di gestione temporanea ed esegui il commit o archiviali nel tuo database locale:

   git commit -s
   

   Per impostazione predefinita, si apre un editor di testo e ti viene chiesto di fornire un messaggio di commit.

3. Fornisci un messaggio di commit nel seguente formato:

   • Riga 1: titolo. Fornisci un riepilogo di una riga della modifica (massimo 50 caratteri). Potresti usare prefissi per descrivere l'area modificata, seguiti da una descrizione della modifica apportata in questo commit, come il seguente esempio contenente una modifica all'interfaccia utente:

     ui: Removes deprecated widget
     

   • Riga 2: riga vuota. Segui il titolo con una riga vuota.

   • Riga 3: corpo. Fornisci una descrizione lunga con una lunghezza massima di 72 caratteri. Descrivi il problema risolto e in che modo. Sebbene il corpo del messaggio sia facoltativo, è utile per gli altri utenti che devono fare riferimento al cambiamento. Assicurati di includere una breve nota di eventuali ipotesi o informazioni di base che potrebbero essere importanti quando un altro collaboratore lavora a questa funzionalità.

   Per leggere un blog sulle descrizioni efficaci dei commit (con esempi), consulta Come scrivere un messaggio di commit Git.

4. Salva il commit.

Al messaggio di commit vengono aggiunti automaticamente un ID modifica univoco, il tuo nome e la tua email forniti durante il giorno repo init.

Carica la modifica per la revisione

Dopo aver eseguito il commit della modifica nella tua cronologia Git personale, caricala su Gerrit:

1. Esegui questo comando per caricare tutti i commit in tutti i progetti:

   repo upload
   

   Tutte le modifiche in tutti i progetti sono incluse nel caricamento.

   .

   Ti viene chiesto di eseguire script hook.

2. Premi A, quindi Invio.

   Ti viene chiesto di approvare il caricamento:

   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)?
   

3. Premi Y, quindi Invio per approvare il caricamento.

Dovresti ricevere un messaggio simile a remote: SUCCESS.

Richiedi una revisione

Al termine del caricamento, il repository fornisce un link alle modifiche in Gerrit. Fai clic sul link per visualizzare le modifiche sul server di revisione, aggiungere commenti o richiedere revisori specifici per la modifica. Tutte le modifiche apportate al codice devono essere esaminate dai proprietari del codice appropriati. Per richiedere una revisione:

1. In Gerrit, fai clic su SUGGERI AI PROPRIETARI:

   

   Figura 1. Suggerisci link ai proprietari in Gerrit.

   Viene visualizzata la finestra di dialogo del revisore. Questa finestra di dialogo contiene un elenco di proprietari di codice che possono esaminare la modifica.

2. Fai clic su un proprietario del codice per aggiungerlo alla tua recensione.

   Il pulsante INVIA è attivato.

3. (Facoltativo) Digita l'indirizzo email di chiunque voglia richiedere il controllo della modifica.

4. (Facoltativo) Fai clic su +1 accanto a Invio automatico per inviare automaticamente la modifica dopo aver ricevuto le approvazioni. Se non fai clic su questo pulsante, la modifica deve essere inviata da un dipendente Google.

5. Fai clic su INVIA per inviare la modifica per la revisione.

I proprietari del codice esaminano le modifiche apportate al codice e ti forniscono un feedback per risolvere o approvare le modifiche.

Determinare lo stato del cambiamento

Per determinare lo stato dei file nella modifica, controlla le seguenti icone accanto ai file nella modifica:

• done (icona segno di spunta): approvato dal proprietario del codice
• clear (icona a forma di croce): non approvato dal proprietario del codice
• access_time (icona dell'orologio): in attesa di approvazione da parte del proprietario del codice

La figura seguente mostra le icone di stato applicate ai file oggetto di una modifica:

Figura 2. Esempio di file con icone che mostrano l'approvazione del proprietario del codice.

Risolvi il feedback e carica una modifica sostitutiva

Se un revisore richiede una modifica all'aggiornamento, puoi modificare il commit all'interno di Git, ottenendo così un nuovo set di patch per la stessa modifica.

Per risolvere il feedback e modificare la modifica:

1. Segui i passaggi 2-4 descritti in Apportare e testare una modifica.

2. Esegui questi comandi per modificare la modifica:

   git add -A
   git commit --amend
   

3. Carica la modifica.

Quando carichi la modifica modificata, sostituisce l'originale sia su Gerrit che nella tua cronologia Git locale.

Risolvi i conflitti di sincronizzazione

Se nella struttura di origine vengono inviate altre modifiche in conflitto con la tua, riceverai un messaggio che indica la presenza di eventuali conflitti. Per risolvere i conflitti:

1. Assicurati di utilizzare il codice più recente:

   repo sync .
   

   Il comando repo sync recupera gli aggiornamenti dal server di origine, quindi tenta di ricollegare automaticamente il tuo HEAD sul nuovo HEAD remoto.

2. Se il rebase automatico non va a buon fine, esegui un rebase manuale:

   repo rebase .
   

3. Risolvi i conflitti di unione. Se non hai un metodo preferito per risolvere i conflitti di unione, puoi utilizzare git mergetool per correggere manualmente i conflitti tra i file.

4. Dopo aver corretto i file in conflitto, esegui questo comando per applicare i nuovi commit:

   git rebase --continue
   

Invia modifica

Dopo che l'invio supera la procedura di revisione e verifica, un revisore di Google deve inviare il codice per tuo conto. Gli altri utenti possono eseguire repo sync per eseguire il pull dell'aggiornamento nei rispettivi client locali.

Dopo aver unito i contenuti inviati, puoi visitare la dashboard Integrazione continua di Android per monitorare quando i contenuti inviati vengono integrati nella struttura ad albero.