Przesyłanie zmian kodu

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

AOSP korzysta z Gerrita, czyli internetowego systemu sprawdzania kodu w projektach, które używają Gita.

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

Zanim prześlesz jakiekolwiek zmiany kodu do AOSP, musisz przeczytać Umowy licencyjne dla współtwórców i nagłówki oraz podpisać jedną z tych umów:

• Jeśli jesteś osobą fizyczną i przesyłasz zmiany tylko w swoim imieniu, podpisz umowę licencyjną dla współtwórców.
• Jeśli jesteś pracownikiem firmy, upewnij się, że Twoja firma podpisała Umowę licencyjną dla współtwórców , która upoważnia Cię do przesyłania zmian w jej imieniu.

Rozpoczynanie gałęzi

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

1. Rozpocznij nową gałąź w odpowiednim repozytorium Git. Gałąź nie jest kopią oryginalnych plików, ale wskaźnikiem do określonego zatwierdzenia, co sprawia, że tworzenie gałęzi lokalnych i przełączanie się między nimi jest operacją o niewielkim obciążeniu. Dzięki gałęziom możesz identyfikować zmiany. Aby rozpocząć gałąź, uruchom to polecenie:

   repo start BRANCH_NAME

   W tym samym repozytorium możesz jednocześnie rozpocząć kilka niezależnych gałęzi. Gałąź BRANCH_NAME jest lokalna w Twoim obszarze roboczym i nie jest uwzględniana ani w Gerrit, ani w końcowym drzewie źródłowym. Gałęzie są też specyficzne dla projektu, w którym pracujesz, więc jeśli w ramach tej samej zmiany musisz zmienić pliki w różnych projektach, będziesz potrzebować gałęzi w każdym projekcie, w którym zmieniasz pliki.

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

   repo status .

   Powinna się wyświetlić nowo utworzona gałąź. Przykład:

   project frameworks/native/                      branch mynewbranch

Wprowadzanie i testowanie zmian

Aby wprowadzić i przetestować zmiany:

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

   repo sync

   Jeśli podczas synchronizacji wystąpią konflikty, wykonaj kroki 2–4 opisane w sekcji Rozwiązywanie konfliktów synchronizacji.

2. Znajdź kod, który chcesz zmienić. Aby znaleźć kod, możesz użyć wyszukiwarki kodu Androida. Za pomocą wyszukiwarki kodu Androida możesz wyświetlić kod źródłowy AOSP w takiej postaci, w jakiej jest on ułożony podczas jego używania. Więcej informacji znajdziesz w artykule Pierwsze kroki z Code Search. Aby wyświetlić cały kod w najnowszej gałęzi AOSP w wyszukiwarce kodu Androida, otwórz stronę https://cs.android.com/android/platform/superproject/.

3. Zmodyfikuj lub dodaj pliki źródłowe. W przypadku wszystkich wprowadzonych zmian:

   • Sprawdź, czy musisz użyć flag uruchamiania funkcji, a jeśli tak, zaimplementuj je w nowym kodzie.

   • Postępuj zgodnie ze sprawdzonymi metodami opisanymi w sekcji Dodawanie nagłówków licencji.

   • W przypadku kodu w Javie postępuj zgodnie z e stylem kodu w Javie dla współtwórców AOSP.

   • Niektóre części AOSP są napisane w Kotlinie (.kt) i 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 dla deweloperów Androida i w przewodniku po interoperacyjności Kotlina i Javy. Więcej informacji o Kotlinie znajdziesz na stronie języka Kotlin .

   • Podczas pisania interfejsów API postępuj zgodnie z wytycznymi dotyczącymi interfejsów API Androida. Dzięki tym wytycznym możesz poznać kontekst decyzji dotyczących interfejsów API Androida. Dodawanie i modyfikowanie interfejsów API platformy jest weryfikowane przez Metalavę.

4. Skompiluj Androida.

5. Przetestuj kompilację.

Przygotowywanie i zatwierdzanie zmian

Zatwierdzenie to podstawowa jednostka kontroli wersji w Git, która składa się z migawki struktury katalogów i zawartości plików całego projektu. Aby zatwierdzić zmiany:

1. Domyślnie Git rejestruje, ale nie śledzi wprowadzanych zmian. Aby poinstruować Gita, aby śledził zmiany, musisz oznaczyć lub przygotować te zmiany do uwzględnienia w zatwierdzeniu. Aby przygotować zmianę, uruchom to polecenie:

   git add -A

   To polecenie śledzi zmiany wprowadzone w dowolnych plikach.

2. Pobierz pliki z obszaru przygotowania i zatwierdź je lub zapisz w lokalnej bazie danych:

   git commit -s

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

3. Podaj komunikat zatwierdzenia w tym formacie:

   • Wiersz 1: nagłówek. Podaj jednolinijkowe podsumowanie zmiany (maksymalnie 50 znaków). Używaj prefiksów, aby opisać zmieniany obszar, a następnie opis zmiany wprowadzonej w tym zatwierdzeniu. Przykład poniżej zawiera zmianę interfejsu użytkownika:

     ui: Removes deprecated widget
     

   • Wiersz 2: pusty wiersz. Po nagłówku dodaj pusty wiersz.

   • Wiersz 3: treść. Podaj długi opis, który będzie zawijał się do maksymalnie 72 znaków. Opisz, jaki problem rozwiązuje zmiana i jak to robi. Treść jest opcjonalna, ale może być przydatna dla innych osób, które będą musiały się do niej odwołać. Pamiętaj, aby dodać krótką notatkę o wszelkich założeniach lub informacjach, które mogą być ważne, gdy inny współtwórca będzie pracował nad tą funkcją.

   Aby przeczytać bloga o dobrych opisach zatwierdzeń (z przykładami), zobacz Jak napisać komunikat zatwierdzenia w Git.

4. Zapisz zatwierdzenie.

Do komunikatu zatwierdzenia automatycznie dodawany jest unikalny identyfikator zmiany oraz Twoje imię i nazwisko oraz adres e-mail podane podczas repo init.

Przesyłanie zmiany do sprawdzenia

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

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

   repo upload

   Wszystkie zmiany we wszystkich projektach są uwzględniane w przesłaniu.

   .

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

2. Naciśnij a , a potem Enter.

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

   Upload project frameworks/native/ to remote branch android17-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. Aby zatwierdzić przesłanie, naciśnij y , a potem Enter.

Powinien się wyświetlić komunikat podobny do remote: SUCCESS.

Prośba o sprawdzenie

Po pomyślnym przesłaniu Repo wyświetli link do zmian w Gerrit. Kliknij link, aby wyświetlić zmiany na serwerze sprawdzania, dodać komentarze lub poprosić o sprawdzenie zmiany przez konkretnych weryfikatorów. Wszystkie zmiany w kodzie muszą zostać sprawdzone przez odpowiednich właścicieli kodu.

Aby poprosić o sprawdzenie:

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

   

   Rysunek 1. Link „Zaproponuj właścicieli” w Gerrit.

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

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

   Przycisk SEND (Wyślij) zostanie aktywowany.

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

4. Kliknij SEND (Wyślij), aby wysłać zmianę do sprawdzenia.

Właściciele kodu sprawdzą Twoje zmiany w kodzie, a jeśli je zaakceptują, wybiorą zmianę i scalą ją z wewnętrzną gałęzią deweloperską.

Określanie stanu zmiany

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

• done (ikona znacznika wyboru ): zatwierdzone przez właściciela kodu
• clear (ikona krzyżyka): niezatwierdzone przez właściciela kodu
• access_time (zegar ikona): oczekuje na zatwierdzenie przez właściciela kodu

Na ilustracji poniżej widać te ikony stanu zastosowane do plików w zmianie:

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

Rozwiązywanie problemów i przesyłanie zmiany zastępczej

Jeśli weryfikator poprosi o zmodyfikowanie aktualizacji, możesz zmienić zatwierdzenie w Git, co spowoduje utworzenie nowego zestawu poprawek w tej samej zmianie.

repo start EXISTING_BRANCH_NAME

Aby rozwiązać problemy i zmienić zmianę:

1. Wykonaj kroki 2–4 opisane w sekcji Wprowadzanie i testowanie zmian.

2. Aby zmienić zmianę, uruchom te polecenia:

   git add -A
   git commit --amend

3. Prześlij zmianę.

Gdy prześlesz zmienioną zmianę, zastąpi ona oryginalną 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 powodują konflikt z Twoimi, otrzymasz komunikat o konflikcie. Aby rozwiązać konflikty:

1. Upewnij się, że pracujesz z najnowszym kodem:

   repo sync .

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

2. Jeśli automatyczna zmiana bazy nie powiedzie się, wykonaj ręczną zmianę bazy:

   repo rebase .

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

4. Gdy rozwiążesz konflikty w plikach, uruchom to polecenie, aby zastosować nowe zatwierdzenia:

   git rebase --continue

Przesyłanie zmiany

Gdy przesłana zmiana przejdzie proces sprawdzania i weryfikacji, właściciel kodu prześle kod za Ciebie w gałęzi, w której zmiana została sprawdzona, lub w gałęzi wewnętrznej.

Po scaleniu przesłanej zmiany możesz otworzyć panel integracji ciągłej Androida , aby sprawdzić, kiedy przesłane zmiany zostaną zintegrowane z drzewem.