Inviare modifiche al codice

Questa pagina descrive la procedura completa per inviare una modifica al codice all'Android Open Source Project (AOSP), inclusa la richiesta di revisione e il monitoraggio delle 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 dei collaboratori

Prima di apportare modifiche al codice per AOSP, devi leggere i contratti di licenza e le intestazioni dei collaboratori e firmare uno dei seguenti contratti:

• In qualità di collaboratore privato che fornisce contributi solo per tuo conto, firma il Contratto di licenza per i collaboratori privati.
• In qualità di dipendente di un'azienda, assicurati che la tua azienda abbia firmato il Contratto di licenza per i collaboratori aziendali autorizzandoti a fornire contributi per suo conto.

Nota: per apportare modifiche ai progetti a monte utilizzati da Android, devi apportarle direttamente al progetto. Per ulteriori informazioni, consulta Contribuire ai progetti upstream.

Avvia un ramo

Per ogni modifica del codice che intendi apportare, svolgi i seguenti passaggi:

1. Avvia un nuovo branch nel repository Git pertinente. Un ramo non è una copia degli originali; è un puntatore a un commit specifico, il che rende la creazione di rami locali e il passaggio da uno all'altro un'operazione leggera. Con l'utilizzo dei branch, puoi identificare le modifiche rispetto a un altro branch. Esegui questo comando per avviare un ramo:

   repo start BRANCH_NAME

   Puoi avviare più branch indipendenti contemporaneamente nello stesso repository. Il ramo BRANCH_NAME è locale per il tuo workspace e non è incluso in Gerrit o nella struttura ad albero delle origini finale. I branch sono specifici anche per il progetto in cui ti trovi, quindi se devi modificare i file in progetti diversi nell'ambito della stessa modifica, dovrai avere un branch 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. Ad esempio:

   project frameworks/native/                      branch mynewbranch

   Nota: puoi anche utilizzare repo branches per ottenere un elenco di tutti i rami, con il ramo corrente (se presente) preceduto da un asterisco (*).

Apporta e testa la modifica

Per apportare e testare la modifica:

1. Per assicurarti di utilizzare il codice di base più recente, esegui una sincronizzazione dell'intero codebase:

   repo sync

   Nota: per sincronizzare solo il progetto corrente, aggiungi un punto (.) al comando repo sync: repo sync .. La sincronizzazione del progetto corrente è più veloce della sincronizzazione dell'intero repository.

   Se si verificano conflitti durante la sincronizzazione, consulta i passaggi 2-4 di Risolvere i conflitti di sincronizzazione.

2. Trova il codice da modificare. Per trovare il codice, ti consigliamo di utilizzare Android Code Search. Puoi utilizzare la ricerca di codice Android per visualizzare il codice sorgente di AOSP così come è strutturato quando lo utilizzi effettivamente. Per ulteriori informazioni, consulta la guida introduttiva all'utilizzo di Ricerca codice. Per visualizzare tutto il codice del ramo di release AOSP più recente in Ricerca codice Android, vai a https://cs.android.com/android/platform/superproject/.

3. Modificare o aggiungere file di origine. Per eventuali modifiche apportate:

   • Determina se devi utilizzare i flag di lancio delle funzionalità e, in caso affermativo, implementali per il nuovo codice.

   • Segui le best practice descritte in Includi intestazioni della licenza.

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

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

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

4. Build Android.

5. Esegui il test della build.

Esegui il commit e inserisci la modifica nella fase

Un commit è l'unità di base del controllo delle revisioni in Git e consiste in un scatto della struttura della directory e dei contenuti dei file per l'intero progetto. Per eseguire il commit della modifica:

1. Per impostazione predefinita, Git registra, ma non monitora le modifiche apportate. Per indicare a Git di monitorare le modifiche, devi contrassegnarle o inserirle in una fase per includerle in un commit. Esegui questo comando per eseguire la gestione delle modifiche:

   git add -A

   Questo comando monitora le modifiche apportate a qualsiasi file.

   Nota: se vuoi solo monitorare le modifiche a un file specifico, utilizza git add filename.
   Nota: oltre a monitorare le modifiche ai file, git add può essere utilizzato per eseguire altre operazioni, come le modifiche e le eliminazioni dei file in anteprima.

2. Prendi i file nell'area di staging e esegui il commit o archiviali nel 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). Valuta la possibilità di utilizzare i prefissi per descrivere l'area modificata, seguita da una descrizione della modifica apportata in questo commit, ad esempio l'esempio seguente contenente una modifica all'interfaccia utente:

     ui: Removes deprecated widget
     

   • Riga 2: riga vuota. Inserisci una riga vuota dopo il titolo.

   • Riga 3: Testo. Fornisci una descrizione lunga che si inserisce a capo obbligatoriamente al massimo dopo 72 caratteri. Descrivi il problema risolto dalla modifica e come. Anche se il corpo è facoltativo, è utile per gli altri utenti che devono fare riferimento alla modifica. Assicurati di includere una breve nota su eventuali presupposti o informazioni di contesto che potrebbero essere importanti quando un altro collaboratore lavora a questa funzionalità.

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

4. Salva il commit.

Un ID modifica univoco e il tuo nome e indirizzo email, forniti durante repo init, vengono aggiunti automaticamente al messaggio del commit.

Carica la modifica per la revisione

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

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

   repo upload

   Nel caricamento sono incluse tutte le modifiche in tutti i progetti.

   Nota: per caricare le modifiche solo nel progetto corrente, aggiungi un punto (.) al comando repo upload: repo upload ..
   Nota: se stai lavorando a una modifica che richiede modifiche ai file di più progetti, utilizza un argomento in Gerrit per collegare le modifiche, indipendentemente dall'utilizzo di repo upload o repo upload .. L'argomento Gerrit garantisce che le modifiche vengano mantenute insieme ai fini dei test pre-invio e tramite l'unione automatica. Per ulteriori informazioni, consulta Utilizzare Topics

   Ti viene chiesto di eseguire script di hook.

2. Premi A, quindi Invio.

   Ti viene chiesto di approvare il caricamento:

   Upload project frameworks/native/ to remote branch android15-qpr2-release:
   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)?
   

   Nota: se hai avviato più branch nello stesso repository, ti viene chiesto di selezionare quelli da caricare rimuovendo il commento da questi branch nell'editor di testo.

3. Premi y e poi Invio per approvare il caricamento.

Dovresti ricevere un messaggio simile a remote: SUCCESS.

Richiedi una revisione

Dopo un caricamento riuscito, Repo ti 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 al codice devono essere esaminate dai proprietari del codice appropriati.

Nota: le configurazioni di release incluse in AOSP sono definite da Google. Google non accetta contributi per aggiornare o modificare i flag di rilascio delle funzionalità di una configurazione. In alternativa, puoi definire le tue configurazioni di release personalizzate, inclusi i valori predefiniti dei flag, nei tuoi fork di AOSP. Per ulteriori informazioni sulle configurazioni di rilascio, consulta Impostare i valori dei flag di lancio delle funzionalità.

Per richiedere una revisione:

1. In Gerrit, fai clic su SUGGERI PROPRIETARI:

   

   Figura 1. Suggerisci il link dei 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 revisione.

   Nota: per capire in che modo vengono determinati i proprietari, consulta il backend find-owners.

   Il pulsante INVIA è attivo.

3. (Facoltativo) Digita l'indirizzo email di altre persone che vuoi che esaminino la modifica.

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

I proprietari del codice esaminano le modifiche al codice e, se accettate, scelgono la modifica e la uniscono al ramo di sviluppo interno.

Determinare lo stato della modifica

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

• (icona di spunta): approvato dal proprietario del codice
• (icona a forma di croce): non approvato dal proprietario del codice
• (icona della sveglia): in attesa di approvazione da parte del proprietario del codice

La figura seguente mostra queste icone di stato applicate ai file in una modifica:

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

Risolvere il feedback e caricare una modifica sostitutiva

Se un revisore richiede una modifica all'aggiornamento, puoi emendare il commit in Git, il che genera un nuovo set di patch per la stessa modifica.

Nota: se hai creato altri branch e hai eseguito altri commit dopo aver caricato una modifica, probabilmente lavorerai nel branch di uno di questi commit e non nel branch della modifica originale. Pertanto, prima di poter risolvere il feedback per il ramo originale, devi accedere a quel ramo utilizzando il comando repo start EXISTING_BRANCH_NAME.

Per risolvere il feedback e modificare la modifica:

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

2. Esegui i seguenti comandi per modificare la modifica:

   git add -A
   git commit --amend

3. Carica la modifica.

Quando carichi la modifica modificata, questa sostituisce quella originale sia su Gerrit sia nella cronologia Git locale.

Risolvere i conflitti di sincronizzazione

Se vengono inviate altre modifiche all'albero di origine in conflitto con le tue, riceverai un messaggio che ti informa della presenza di 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 eseguire automaticamente il rebase del HEAD sul nuovo HEAD remoto.

2. Se il ricoinvolgimento automatico non va a buon fine, esegui un ricoinvolgimento 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 un invio ha superato 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 scaricare l'aggiornamento nei rispettivi client locali.

Una volta unito il tuo invio, puoi visitare la dashboard Integrazione continua di Android per monitorare quando i tuoi invii vengono integrati nell'albero.