Inviare modifiche al codice

Questa pagina descrive l'intera procedura di invio di 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.

Firma dei contratti di licenza del collaboratore

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

• Se contribuisci come privato e solo per tuo conto, firma il Contratto di licenza per i collaboratori individuali.
• In qualità di dipendente di una società, assicurati che la tua azienda abbia firmato il Corporate Contributor License Agreement che ti autorizza a dare contributi per suo conto.

Avviare un ramo

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

1. Avvia un nuovo branch 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 apportate. 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 per il tuo spazio di lavoro e non è incluso né in Gerrit né nell'albero delle origini finale. I rami sono specifici anche per il progetto in cui ti trovi, quindi se devi modificare i file in 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 che hai appena creato. Ad esempio:

   project frameworks/native/                      branch mynewbranch

Apporta la modifica e testala

Segui questi passaggi per apportare e testare la modifica:

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

   repo sync

   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, valuta la possibilità di utilizzare Android Code Search. Puoi utilizzare Android Code Search per visualizzare il codice sorgente AOSP così come viene visualizzato quando lo utilizzi effettivamente. Per saperne di più, consulta Guida introduttiva a Code Search. Per visualizzare tutto il codice nell'ultimo ramo di rilascio AOSP all'interno di Android Code Search, 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 di licenza.

   • Per il codice Java, segui lo stile del 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 saperne di più su Kotlin in Android, consulta la guida di stile di Kotlin e la guida all'interoperabilità Kotlin-Java per gli sviluppatori Android. Per indicazioni più dettagliate su Kotlin, visita 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 alle API della piattaforma vengono convalidate da Metalava.

4. Crea Android.

5. Testa la build.

Organizza e conferma la modifica

Un commit è l'unità di base del controllo delle revisioni in Git e consiste in uno snapshot della struttura delle directory e dei contenuti dei file per l'intero progetto. Per applicare la modifica:

1. Per impostazione predefinita, Git registra ma non tiene traccia delle modifiche apportate. Per indicare a Git di monitorare le modifiche, devi contrassegnarle o prepararle per l'inclusione in un commit. Esegui questo comando per preparare la modifica:

   git add -A

   Questo comando tiene traccia delle modifiche apportate ai file.

2. Prendi i file nell'area di gestione temporanea 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 prefissi per descrivere l'area che hai modificato, seguiti da una descrizione della modifica apportata in questo commit, ad esempio il seguente esempio contenente una modifica dell'interfaccia utente:

     ui: Removes deprecated widget
     

   • Riga 2: riga vuota. Dopo il titolo, inserisci una riga vuota.

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

   Per leggere un blog sulle descrizioni dei commit (con esempi), consulta How to Write a Git Commit Message.

4. Salva il commit.

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

Carica la modifica per la revisione

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

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

   repo upload

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

   Ti viene chiesto di eseguire gli script hook.

2. Premi A, quindi Invio.

   Ti viene chiesto di approvare il caricamento:

   Upload project frameworks/native/ to remote branch android16-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)?
   

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.

Per richiedere una revisione:

1. In Gerrit, fai clic su SUGGERISCI PROPRIETARI:

   

   Figura 1. Suggerisci il link ai proprietari in Gerrit.

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

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

   Il pulsante INVIA è attivato.

3. (Facoltativo) Digita l'indirizzo email di chiunque altro voglia rivedere la tua 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, selezionano 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:

• 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 orologio): 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 modificare il commit in Git, il che comporta un nuovo patchset sulla stessa modifica.

Per risolvere il problema del feedback e modificare la tua modifica:

1. Segui i passaggi 2-4 della sezione Apportare e testare la modifica.

2. Esegui i seguenti comandi per modificare la tua modifica:

   git add -A
   git commit --amend

3. Carica la modifica.

Quando carichi la modifica emendata, questa sostituisce l'originale sia su Gerrit sia nella cronologia Git locale.

Risolvere i conflitti di sincronizzazione

Se vengono inviate altre modifiche all'albero di origine che sono in conflitto con le tue, ricevi 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 di 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 risolvere 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

Una volta superata la procedura di revisione e verifica, il proprietario del codice lo invia per tuo conto, nel ramo in cui è stata esaminata la modifica o in un ramo interno.

Una volta unita la tua proposta, puoi visitare la dashboard Integrazione continua di Android per monitorare quando le tue proposte vengono integrate nell'albero.