Przesyłanie zmian kodu

Na tej stronie znajdziesz opis całego procesu przesyłania zmiany kodu do Projektu Android Open Source (AOSP), w tym informacje o tym, jak poprosić o sprawdzenie i śledzić zmiany.

AOSP korzysta z Gerrit, czyli internetowego systemu do sprawdzania kodu w projektach, które używają Git.

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

Zanim wprowadzisz jakiekolwiek zmiany w kodzie AOSP, musisz przeczytać umowy licencyjne i nagłówki dla współtwórców i podpisać jedną z tych umów:

• Jeśli jesteś osobą fizyczną i publikujesz treści wyłącznie w swoim imieniu, podpisz Umowę licencyjną na treści dla osób fizycznych.
• Jeśli jesteś pracownikiem korporacji, upewnij się, że Twoja firma podpisała Umowę licencyjną dla współtwórców korporacyjnych, która upoważnia Cię do wnoszenia wkładu w jej imieniu.

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, ale wskaźnikiem konkretnego zatwierdzenia, co sprawia, że tworzenie lokalnych gałęzi i przełączanie się między nimi jest prostą operacją. Dzięki gałęziom możesz identyfikować zmiany w poszczególnych wersjach. Aby utworzyć 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 się znajdujesz. Jeśli w ramach tej samej zmiany musisz zmodyfikować pliki w różnych projektach, w każdym z nich musisz mieć gałąź, w której zmieniasz pliki.

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

   repo status .

   Powinna być widoczna nowo utworzona gałąź. Na przykład:

   project frameworks/native/                      branch mynewbranch

Wprowadzanie i testowanie zmian

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 kroki 2–4 z artykułu Rozwiązywanie konfliktów synchronizacji.

2. Znajdź kod, który chcesz zmienić. Aby znaleźć kod, możesz skorzystać z 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 korzystania z niego. Więcej informacji znajdziesz w artykule Pierwsze kroki z Code Search. Aby wyświetlić cały kod w najnowszej gałęzi wersji AOSP w wyszukiwarce kodu Androida, otwórz https://cs.android.com/android/platform/superproject/.

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

   • Określ, czy musisz używać flag uruchamiania funkcji, a jeśli tak, zaimplementuj je w nowym kodzie.

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

   • W przypadku kodu w języku Java postępuj zgodnie z zasadami stylu kodu w języku Java w AOSP dla współtwórców.

   • Niektóre części AOSP są napisane w Kotlinie (.kt). Możesz używać tego języka w obszarach platformy, które są już w nim napisane. Więcej informacji o Kotlinie w Androidzie znajdziesz w przewodniku po stylu Kotlina i przewodniku po współdziałaniu Kotlina z Javą dla deweloperów Androida. Więcej informacji o języku Kotlin znajdziesz na stronie poświęconej temu językowi.

   • Podczas pisania interfejsów API postępuj zgodnie z wytycznymi dotyczącymi interfejsów API na Androida. Zapoznaj się z tymi wytycznymi, aby poznać kontekst decyzji dotyczących interfejsu API Androida. Dodawanie i modyfikowanie interfejsów API platformy jest weryfikowane przez Metalavę.

4. Tworzenie aplikacji na Androida

5. Przetestuj kompilację

Przygotowanie i zatwierdzenie zmiany

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

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

   git add -A

   To polecenie śledzi zmiany wprowadzone w dowolnych plikach.

2. Przenieś pliki z obszaru przejściowego i zatwierdź je lub zapisz w lokalnej bazie danych:

   git commit -s

   Domyślnie otworzy się edytor tekstu z prośbą o podanie wiadomości o zatwierdzeniu.

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ć obszar, w którym wprowadzono zmiany, a następnie podaj opis zmiany w tym zatwierdzeniu. Oto przykład zmiany w interfejsie użytkownika:

     ui: Removes deprecated widget
     

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

   • Wiersz 3: treść. Podaj długi opis, który jest zawijany twardo po 72 znakach. Opisz, jaki problem rozwiązuje zmiana i w jaki sposób. Treść jest opcjonalna, ale może być przydatna dla innych osób, które będą chciały wrócić do tej zmiany. Pamiętaj, aby dodać krótką notatkę z wszelkimi założeniami lub informacjami, 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 How to Write a Git Commit Message (Jak napisać wiadomość zatwierdzenia w Git).

4. Zapisz zatwierdzenie.

Do wiadomości o zatwierdzeniu automatycznie dodawany jest unikalny identyfikator zmiany oraz Twoje imię i nazwisko oraz adres e-mail, które zostały podane podczas repo init.

Prześlij zmianę do sprawdzenia

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

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

   repo upload

   Przesłane zostaną 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 android16-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. Naciśnij y, a następnie Enter, aby zatwierdzić przesyłanie.

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

Poproś o sprawdzenie

Po przesłaniu zmian Repo podaje link do nich w Gerrit. Kliknij link, aby wyświetlić zmiany na serwerze sprawdzania, dodać komentarze lub poprosić o sprawdzenie zmian 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. Sugerowanie właścicieli w Gerrit.

   Pojawi się okno dialogowe recenzenta. W tym oknie dialogowym znajduje się lista właścicieli kodu, którzy mogą sprawdzić Twoją zmianę.

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

   Przycisk WYŚLIJ jest aktywny.

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

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

Właściciele kodu sprawdzają zmiany w kodzie i jeśli je zaakceptują, wybierają zmianę i scalają ją z wewnętrzną gałęzią deweloperską.

Określanie stanu zmiany

Aby sprawdzić stan plików w zmianie, poszukaj obok nich tych ikon:

• done (checkmark icon): Zatwierdzono przez właściciela kodu
• clear (ikona krzyżyka): Nie zatwierdzono przez właściciela kodu
• access_time (zegar): oczekuje na zatwierdzenie przez właściciela kodu

Na ilustracji poniżej widać 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 zgłoszonych w opiniach i przesyłanie zmiany zastępczej

Jeśli weryfikator poprosi o zmianę aktualizacji, możesz zmodyfikować zatwierdzenie w Git, co spowoduje utworzenie nowego zestawu poprawek w ramach tej samej zmiany.

.

Aby uwzględnić opinię i wprowadzić zmiany:

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

2. Aby wprowadzić zmiany, uruchom te polecenia:

   git add -A
   git commit --amend

3. Prześlij zmianę.

Gdy prześlesz poprawioną zmianę, zastąpi ona oryginalną wersję 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 wiadomość o konfliktach. Aby rozwiązać konflikty:

1. Upewnij się, że pracujesz z najnowszą wersją kodu:

   repo sync .

   Polecenie repo sync pobiera aktualizacje z serwera źródłowego, a następnie próbuje automatycznie przenieść bazę HEAD na nowy zdalny HEAD.

2. Jeśli automatyczne przeniesienie zmian nie powiedzie się, wykonaj je ręcznie:

   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 problem z konfliktującymi plikami, uruchom to polecenie, aby zastosować nowe zmiany:

   git rebase --continue

Prześlij zmianę

Gdy przesłany kod przejdzie proces weryfikacji, jego właściciel przesyła go w Twoim imieniu do gałęzi, w której zmiany zostały sprawdzone, lub do gałęzi wewnętrznej.

Po scaleniu przesłanych zmian możesz przejść do panelu Android Continuous Integration, aby monitorować, kiedy zostaną one zintegrowane z drzewem.