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:
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.
(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:
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.
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ź dohttps://cs.android.com/android/platform/superproject/main
.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.
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:
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.
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.
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).
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:
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.
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)?
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:
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ę.
Kliknij właściciela kodu, aby dodać go do opinii.
Aktywowano przycisk WYŚLIJ.
(Opcjonalnie) Wpisz adresy e-mail osób, które mają sprawdzić Twoją zmianę.
(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.
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:
- (ikona symbolu zaznaczenia): Zatwierdzenie przez właściciela kodu
- (ikona krzyżyka): Niezatwierdzone przez właściciela kodu
- (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:
Wykonaj kroki 2–4 z sekcji Wprowadzanie i testowanie zmiany.
Aby poprawić zmianę, uruchom następujące polecenia:
git add -A git commit --amend
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:
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 elemencieHEAD
.Jeśli automatyczna zmiana się nie uda, wykonaj ręczną korektę:
repo rebase .
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.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.