Wprowadź zmiany w kodzie

Na tej stronie opisujemy cały proces przesyłania zmiany kodu do projektu Android Open Source Project (AOSP), w tym sposób zgłaszania prośby o sprawdzenie i śledzenia zmian.

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

Podpisywanie umów licencyjnych 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:

• Jako pojedynczy współtwórca, który dodaje treści tylko w Twoim imieniu, podpisz Umowę licencyjną dla pojedynczego współtwórcy.
• Jako pracownik pracujący dla korporacji upewnij się, że masz podpisaną Umowę licencyjną dla współtwórcy korporacyjnego, która upoważnia Cię do dokonywania darowizn w jej imieniu.

Utwórz gałąź

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

1. Uruchom nową gałąź w odpowiednim repozytorium Git. Gałąź nie jest kopią oryginalnych plików. Jest to wskaźnik do konkretnego zatwierdzenia, dzięki czemu tworzenie gałęzi lokalnych i przełączanie się między nimi jest bardzo proste. 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 pracujesz, więc jeśli w ramach tej samej zmiany musisz zmienić pliki w różnych projektach, musisz utworzyć gałąź w każdym projekcie, w którym zmieniasz pliki.

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

   repo status .
   

   Zobaczysz nowo utworzoną gałąź. Na przykład:

   project frameworks/native/                      branch mynewbranch
   

Wprowadź i przetestuj zmianę

Aby wprowadzić i przetestować zmianę, wykonaj następujące czynności:

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

   repo sync
   

   Jeśli podczas synchronizacji wystąpią jakiekolwiek konflikty, zapoznaj się z krokami 2–4 w artykule Rozwiązywanie konfliktów synchronizacji.

2. Znajdź kod, który chcesz zmienić. Aby znaleźć kod, skorzystaj z wyszukiwarki kodu na Androidzie. Za pomocą narzędzia Android Code Search możesz wyświetlić kod źródłowy AOSP w postaci, w jakiej jest on w rzeczywistości używany. Więcej informacji na ten temat można znaleźć w artykule Pierwsze kroki z wyszukiwarką Code Search. 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. Zmień lub dodaj pliki źródłowe. Dla wszystkich wprowadzonych zmian:

   • Postępuj zgodnie ze sprawdzonymi metodami opisanymi w artykule Uwzględnij nagłówki licencji.

   • W przypadku kodu w Javie postępuj zgodnie ze stylami kodu Java AOSP dla współtwórców.

   • Niektóre fragmenty AOSP są napisane w języku Kotlin (.kt) i można z niego korzystać w obszarach platformy, które są już napisane w języku Kotlin. Więcej informacji na temat Kotlin w Androidzie znajdziesz w przewodniku po Kotlin w języku Kotlin i w przewodniku na temat interoperacyjności Kotlin-Java dla programistów Androida. Bardziej szczegółowe wskazówki dotyczące języka Kotlin znajdziesz na stronie 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. Utwórz Androida

5. Testowanie kompilacji.

Przygotuj i zatwierdź zmianę

commit to podstawowa jednostka kontroli wersji w Git. Składa się ze zrzutu struktury katalogu i zawartości plików dla całego projektu. Aby zatwierdzić zmianę, wykonaj te czynności:

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

   git add -A
   

   To polecenie śledzi zmiany wprowadzone w plikach.

2. Pobierz pliki z obszaru roboczego i zatwierdź je lub zapisz 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, aby opisać zmieniony obszar, a potem opisanie zmiany wprowadzonej w tym zatwierdzeniu, np. przykład zmiany interfejsu:

     ui: Removes deprecated widget
     

   • Wiersz 2: pusty wiersz. Przejdź do nagłówka pustym wierszem.

   • Wiersz 3: treść. Podaj długi opis, który nie może przekraczać 72 znaków. Opisz problem, który rozwiązuje ta zmiana, i w jaki sposób. Choć treść jest opcjonalna, może być pomocna dla innych osób, które chcą się powołać na zmianę. Pamiętaj, aby podać krótką notatkę o wszelkich założeniach i informacjach dodatkowych, które mogą być istotne przy pracy nad tą funkcją przez innego użytkownika.

   Aby przeczytać bloga z dokładnymi opisami zatwierdzenia (z przykładami), przeczytaj artykuł How to Write a Git Commit Message (Jak napisać wiadomość zatwierdzenia Git).

4. Zapisz zatwierdzenie.

Unikalny identyfikator zmiany, Twoje imię i nazwisko oraz adres e-mail podane w repo init są automatycznie dodawane do wiadomości z prośbą o zatwierdzenie.

Przesyłanie zmiany do sprawdzenia

Po zatwierdzeniu zmiany w osobistej historii Git prześlij ją do narzędzia Gerrit:

1. Uruchom to polecenie, aby przesłać wszystkie zatwierdzenia we wszystkich projektach:

   repo upload
   

   W przesyłanym pliku są uwzględniane 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. Naciśnij Y, a następnie Enter, by zatwierdzić przesyłanie.

Powinna wyświetlić się wiadomość podobna do tej: remote: SUCCESS.

Poproś o sprawdzenie

Po przesłaniu pliku Repo wyświetli link do zmian w Gerrit. Kliknij link, aby wyświetlić zmiany na serwerze sprawdzania, dodać komentarze lub poprosić o wybranie konkretnych weryfikatorów. Wszystkie zmiany w kodzie muszą sprawdzać odpowiedni właściciele. Aby poprosić o sprawdzenie:

1. W Gerrit kliknij ZASUGERUJ WŁAŚCICIELE:

   

   Rysunek 1. Link do sugestii właścicieli w narzędziu Gerrit.

   Pojawi się okno dialogowe recenzenta. Zawiera ono listę właścicieli kodu, którzy mogą sprawdzić zmianę.

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

   Aktywowano przycisk WYŚLIJ.

3. (Opcjonalnie) Wpisz adresy e-mail osób, które mają 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ć zmianę w Twoim imieniu.

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

Właściciele kodu sprawdzają zmiany w kodzie i przekazują informacje zwrotne, aby umożliwić Ci wprowadzenie lub zatwierdzenie zmian.

Określ stan zmiany

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

• done (ikona symbolu zaznaczenia): Zatwierdzenie przez właściciela kodu
• clear (ikona krzyżyka): Niezatwierdzone przez właściciela kodu
• access_time (ikona zegara): oczekuje na zatwierdzenie przez właściciela kodu

Na ilustracji poniżej przedstawiono ikony stanu zastosowane do plików w wyniku zmiany:

Rysunek 2. Przykładowe pliki z ikonami oznaczającymi zgodę właściciela kodu.

Odpowiedz na opinię i prześlij zmianę dotyczącą urządzenia na wymianę

Jeśli weryfikator poprosi o modyfikację aktualizacji, możesz to zrobić w Git. Spowoduje to utworzenie nowego zestawu poprawek dla tej samej zmiany.

Aby rozwiązać problem i wprowadzić zmiany:

1. Wykonaj kroki 2–4 z sekcji Wprowadzanie i testowanie zmiany.

2. Aby poprawić zmianę, uruchom następujące polecenia:

   git add -A
   git commit --amend
   

3. Prześlij zmianę.

Gdy prześlesz poprawioną zmianę, zastąpi ona oryginał zarówno w Gerrit, 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 automatyczna zmiana się nie uda, wykonaj ręczną korektę:

   repo rebase .
   

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

4. Gdy rozwiążesz konflikt plików, uruchom to polecenie, aby zastosować nowe zatwierdzenia:

   git rebase --continue
   

Prześlij zmianę

Gdy Twoje zgłoszenie przejdzie proces weryfikacji i weryfikacji, weryfikator Google musi przesłać go za Ciebie. Inni użytkownicy mogą uruchomić repo sync, aby pobrać aktualizację do odpowiednich klientów lokalnych.

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.