Wprowadź zmiany w kodzie

Ta strona zawiera opis całego procesu przesyłania zmian kodu do Projektu Android Open Source (AOSP), w tym sposobu żądania sprawdzenia i śledzenia zmian.

W przypadku projektów wykorzystujących Gita AOSP opiera się na Gerrit – internetowym systemie weryfikacji kodu.

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

Zanim prześlesz jakiekolwiek zmiany w kodzie AOSP, musisz przeczytać Umowy licencyjne i nagłówki 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.

.

Rozpoczęcie 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ą. Za pomocą gałęzi, możesz wzajemnie identyfikować zmiany. Uruchom to polecenie, aby uruchomić gałąź:

   repo start BRANCH_NAME

   W tym samym repozytorium możesz uruchomić kilka niezależnych gałęzi jednocześnie. Gałąź BRANCH_NAME jest lokalna dla Twojego obszaru roboczego i nie znajduje się w Gerrit 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ł. Na przykład:

   project frameworks/native/                      branch mynewbranch

Wprowadź i sprawdź zmiany

Aby wprowadzić i przetestować zmianę, wykonaj te czynności:

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 Androida, przejdź do https://cs.android.com/android/platform/superproject/main.

3. Modyfikować lub dodawać pliki źródłowe. Dla wszystkich 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.

   • Pisząc interfejsy API, przestrzegaj wytycznych dotyczących interfejsu API Androida. Skorzystaj z tych wskazówek, aby poznać kontekst, w którym podejmują decyzje dotyczące interfejsu API Androida. Dodawanie i modyfikacje interfejsów API platformy są weryfikowane przez firmę Metalava.

4. Tworzenie aplikacji na Androida.

5. Przetestuj wersję kompilacji.

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ć zmianę, wykonaj te czynności:

1. Domyślnie Git rejestruje, ale nie śledzi wprowadzanych zmian. Aby poinstruować Gita, aby śledził zmiany, musisz je oznaczyć lub zakończyć w celu uwzględnienia w zatwierdzeniu. Aby wprowadzić zmianę, uruchom to polecenie:

   git add -A

   To polecenie śledzi zmiany wprowadzone w dowolnych plikach.

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

   git commit -s

   Domyślnie otworzy się edytor tekstu i wyświetli się prośba o podanie komunikatu 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 taki sposób:

     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. Choć treść jest opcjonalna, może być pomocna dla innych osób, które chcą się dowiedzieć o zmianie. 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. Link do sugestii właścicieli w narzędziu Gerrit.

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

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

   Aktywowano przycisk WYŚLIJ.

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ć zmianę, gdy uzyskasz zatwierdzenia. Jeśli nie klikniesz tego przycisku, pracownik Google musi przesłać za Ciebie zmiany.

5. Kliknij WYŚLIJ, aby wysłać zmianę 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

Stan plików objętych zmianą możesz sprawdzić obok ikon, których dotyczy zmiana:

• 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 poprawić zmianę, uruchom następujące 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 do drzewa źródłowego zostaną przesłane inne zmiany, które kolidują z Twoim, otrzymasz komunikat o konfliktach. Aby rozwiązać konflikty:

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

   repo sync .

   Polecenie repo sync pobiera aktualizacje z serwera źródłowego, a następnie próbuje automatycznie zmienić bazę HEAD na nowym zdalnym elemencie 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 konfliktów w plikach 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 scaleniu przesłanych treści możesz otworzyć panel ciągłej integracji Androida, aby sprawdzać, kiedy przesłane treści są zintegrowane z drzewem.