Wprowadź zmiany w kodzie

Ta strona opisuje pełny proces przesyłania zmian kodu do Projektu Android Open Source (AOSP), w tym sposób, w jaki można poprosić o sprawdzenie i śledzenie zmian.

AOSP korzysta z Gerrit, internetowego systemu sprawdzania kodu przeznaczonego do projektów korzystających z Git.

Podpisywanie umów licencyjnych dla współtwórców

Zanim wprowadzisz jakiekolwiek zmiany kodu w AOSP, musisz przeczytać porozumienia i nagłówki licencji dla współtwórców oraz podpisać jedną z tych umów:

• Jeśli jesteś indywidualnym współtwórcą i wnosisz swój wkład tylko w Twoim imieniu, podpisz Umowę licencyjną dla indywidualnego współtwórcy.
• Jako pracownik firmy musisz się upewnić, że Twoja firma podpisała Umowę licencyjną dla firm, która upoważnia Cię do wkładu w imieniu firmy.

.

Tworzenie gałęzi

W przypadku każdej zmiany kodu, którą chcesz wprowadzić, wykonaj te czynności:

1. Utwórz nową gałąź w odpowiednim repozytorium Git. Gałąź nie jest kopią oryginalnych plików, lecz wskaźnikiem do konkretnego zatwierdzenia, co sprawia, że tworzenie gałęzi lokalnych i przełączanie się między nimi jest prostą operacją. Dzięki używaniu gałęzi możesz odróżniać od siebie zmiany. Aby utworzyć gałąź, uruchom to polecenie:

   repo start BRANCH_NAME
   

   W tym samym repozytorium możesz uruchomić jednocześnie kilka niezależnych gałęzi. Gałąź BRANCH_NAME jest lokalna dla Twojego workspace i nie jest uwzględniana w Gerricie ani w końcowym drzewie źródłowym. Gałęzie są też powiązane z projektem, w którym się znajdujesz, więc jeśli w ramach tej samej zmiany musisz zmienić pliki w różnych projektach, musisz utworzyć gałąź w każdym z tych projektów.

2. (Opcjonalnie) Sprawdź, czy gałąź została utworzona:

   repo status .
   

   Powinien pojawić się nowo utworzony węzeł. Przykład:

   project frameworks/native/                      branch mynewbranch
   

Wprowadź i sprawdź zmiany

Aby wprowadzić i przetestować zmianę:

1. Aby mieć pewność, że pracujesz z najnowszą bazą kodu, zsynchronizuj całą bazę kodu:

   repo sync
   

   Jeśli podczas synchronizacji wystąpią konflikty, wykonaj czynności opisane w punktach 2–4 artykułu Rozwiązywanie konfliktów podczas synchronizacji.

2. Znajdź kod, który chcesz zmienić. Aby znaleźć kod, możesz użyć wyszukiwarki kodu na Androidzie. Za pomocą wyszukiwarki kodu Android możesz wyświetlić kod źródłowy AOSP w postaci, w której jest on wyświetlany podczas korzystania z niego. Więcej informacji znajdziesz w artykule Pierwsze kroki z wyszukiwarką kodu. Aby wyświetlić cały kod w gałęzi main w wyszukiwarce kodu na Androida, przejdź do https://cs.android.com/android/platform/superproject/main.

3. Modyfikować lub dodawać pliki źródłowe. W przypadku wprowadzonych zmian:

   • Określ, czy musisz użyć flag wdrażania funkcji, a jeśli tak, zastosuj je w przypadku nowego kodu.

   • Stosuj sprawdzone metody opisane w sekcji Dołącz nagłówki licencji.

   • W przypadku kodu w języku Java stosuj się do stylu kodu Java w AOSP dla autorów.

   • Niektóre części AOSP są napisane w języku Kotlin (.kt). Możesz używać Kotlina w obszarach platformy, które są już napisane w tym języku. Więcej informacji o Kotlinie w Androidzie znajdziesz w przewodniku po stylu Kotlina i przewodniku po interoperacyjności Kotlina i Java. Więcej wskazówek dotyczących Kotlina znajdziesz na stronie języka Kotlin.

   • Podczas pisania interfejsów API należy przestrzegać wytycznych dotyczących interfejsów API Androida. Dzięki tym wytycznym możesz poznać kontekst decyzji dotyczących interfejsów API Androida. Dodatki i modyfikacje interfejsów API platformy są weryfikowane przez Metalava.

4. Tworzenie aplikacji na Androida.

5. Przetestuj kompilację.

Etapowanie i zatwierdzanie zmian

Komit to podstawowa jednostka kontroli wersji w Git. Składa się z migawki struktury katalogu i zawartości plików całego projektu. Aby zatwierdzić zmiany:

1. Domyślnie Git rejestruje, ale nie śledzi wprowadzanych zmian. Aby polecić Gitowi śledzenie zmian, musisz je oznaczyć lub umieścić w etapie, aby uwzględnić je w zatwierdzeniu. Aby wprowadzić zmianę, uruchom to polecenie:

   git add -A
   

   To polecenie śledzi zmiany wprowadzone w dowolnych plikach.

2. Pobierz pliki z obszaru pośredniego i zapisz je w lokalnej bazie danych:

   git commit -s
   

   Domyślnie otworzy się edytor tekstu i pojawi się prośba o podanie wiadomości zatwierdzenia.

3. Podaj komunikat zatwierdzenia w tym formacie:

   • Wiersz 1: nagłówek. Podaj jednowierszowe podsumowanie zmiany (maksymalnie 50 znaków). Rozważ użycie prefiksów do opisania zmienionego obszaru, a następnie dodaj opis zmiany wprowadzonej w tym komicie, np. w takim przykładzie, który zawiera zmianę interfejsu:

     ui: Removes deprecated widget
     

   • Wiersz 2: pusty wiersz. Po nagłówku umieść pustą linię.

   • Wiersz 3: Treść. Podaj długi tekst reklamy, który jest automatycznie dzielony na akapity po 72 znakach. Opisz, jaki problem rozwiązuje dana zmiana i w jaki sposób. Chociaż treść jest opcjonalna, może być przydatna innym osobom, które muszą wrócić do zmiany. Pamiętaj, aby dołączyć krótkie notatki dotyczące założeń lub informacji ogólnych, które mogą być ważne dla innych współtwórców tej funkcji.

   Aby przeczytać bloga na temat dobrych opisów zatwierdzeń (z przykładami), zapoznaj się z artykułem Jak napisać wiadomość zatwierdzenia w Git.

4. Zapisz zatwierdzanie.

Unikalny identyfikator zmiany oraz Twoje imię i nazwisko oraz adres e-mail, które zostały podane podczas repo init, są automatycznie dodawane do wiadomości zatwierdzenia.

Przesyłanie zmiany do sprawdzenia

Po zatwierdzeniu zmian w osobistej historii Git prześlij je do Gerrita:

1. Aby przesłać wszystkie commity we wszystkich projektach, uruchom to polecenie:

   repo upload
   

   Przesyłanie obejmuje wszystkie zmiany we wszystkich projektach.

   .

   Pojawi się prośba o uruchomienie skryptów hook.

2. Naciśnij a, a następnie Enter.

   Pojawi się prośba o zatwierdzenie przesyłania:

   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. Aby zatwierdzić przesyłanie, naciśnij y, a potem Enter.

Powinieneś/powinnaś otrzymać wiadomość podobną do remote: SUCCESS.

Poproś o sprawdzenie

Po przesłaniu pliku Repo udostępni link do wprowadzonych przez Ciebie zmian w Gerricie. Kliknij link, aby wyświetlić zmiany na serwerze sprawdzania, dodać komentarze lub poprosić o sprawdzenie zmian przez określonych weryfikatorów. Wszystkie zmiany kodu muszą zostać sprawdzone przez odpowiednich właścicieli kodu. Aby poprosić o sprawdzenie:

1. W Gerrit kliknij SUGGEST OWNERS (Sugeruj właścicieli):

   

   Rysunek 1. Sugeruj link do właścicieli w Gerrit.

   Pojawi się okno recenzenta. To okno zawiera listę właścicieli kodu, którzy mogą sprawdzić Twoją zmianę.

2. Kliknij właściciela kodu, aby dodać go do opinii.

   Przycisk WYŚLIJ jest aktywny.

3. (Opcjonalnie) Wpisz adres e-mail osoby, która ma sprawdzić Twoją zmianę.

4. (Opcjonalnie) Kliknij +1 obok opcji Automatyczne przesyłanie, aby automatycznie przesłać zmiany po otrzymaniu akceptacji. Jeśli nie klikniesz tego przycisku, pracownik Google musi przesłać za Ciebie zmiany.

5. Kliknij WYŚLIJ, aby wysłać zmiany do sprawdzenia.

Właściciele kodu sprawdzają zmiany w kodzie i przekazują Ci opinię, abyś mógł/mogła rozwiązać problem lub zatwierdzić zmiany.

Określanie stanu zmiany

Aby określić stan plików w zmianie, sprawdź obok nich te ikony:

• done (ikona znacznika wyboru): zatwierdzony przez właściciela kodu
• clear (ikona krzyżyka): Nie został zatwierdzony przez właściciela kodu
• access_time (ikona zegara): oczekuje na zatwierdzenie przez właściciela kodu

Na rysunku poniżej widać ikony stanu zastosowane do plików w ramach zmiany:

Rysunek 2. Przykład plików z ikonami potwierdzającymi zatwierdzenie przez właściciela kodu

Rozwiązywanie opinii i przesyłanie zastępczej zmiany

Jeśli weryfikator poprosi o modyfikację Twojego uaktualnienia, możesz zmienić swój zatwierdzony commit w Git, co spowoduje utworzenie nowego zestawu poprawek dla tej samej zmiany.

Aby rozwiązać problem i wprowadzić poprawki:

1. Wykonaj czynności opisane w sekcjach Wprowadzanie i testowanie zmian (kroki 2–4).

2. Aby wprowadzić poprawki, uruchom te polecenia:

   git add -A
   git commit --amend
   

3. Prześlij zmiany.

Gdy prześlesz poprawioną zmianę, zastąpi ona pierwotną zarówno w Gerricie, jak i w lokalnej historii Git.

Rozwiązywanie konfliktów synchronizacji

Jeśli w drzewie źródłowym zostaną przesłane inne zmiany, które są sprzeczne z Twoimi, otrzymasz komunikat o konflikcie. Aby rozwiązać konflikty:

1. Upewnij się, że używasz najnowszej wersji kodu:

   repo sync .
   

   Polecenie repo sync pobiera aktualizacje z serwera źródłowego, a następnie próbuje automatycznie utworzyć nową bazę HEAD na nowym serwerze zdalnym HEAD.

2. Jeśli automatyczne ustawienie bazy nie powiedzie się, wykonaj tę czynność ręcznie:

   repo rebase .
   

3. Rozwiąż konflikty scalania. Jeśli nie masz preferowanej metody rozwiązywania konfliktów podczas łączenia, możesz użyć git mergetool, aby ręcznie rozwiązać konflikty między plikami.

4. Po rozwiązaniu konfliktu uruchom to polecenie, aby zastosować nowe zatwierdzenia:

   git rebase --continue
   

Prześlij zmianę

Gdy przesłane dane przejdą proces weryfikacji, weryfikator Google musi przesłać kod za Ciebie. Inni użytkownicy mogą uruchomić polecenie repo sync, aby pobrać aktualizację do swoich lokalnych klientów.

Po złączeniu przesłanych danych możesz przejść do panelu ciągłej integracji Androida, aby sprawdzić, kiedy przesłane dane zostaną zintegrowane z drzewem.