Przesyłanie zmian kodu

Na tej stronie znajdziesz pełny proces przesyłania zmian kodu do Projektu Android Open Source (AOSP), w tym informacje o tym, jak poprosić o sprawdzenie i śledzić zmiany.

AOSP korzysta z Gerrit, internetowego systemu sprawdzania kodu przeznaczonego do projektów korzystających z Git.

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

Zanim wprowadzisz jakiekolwiek zmiany kodu w AOSP, musisz przeczytać porozumienia i nagłówki dotyczące licencji 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.

.

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, lecz wskaźnikiem do konkretnego zatwierdzenia, co sprawia, że tworzenie gałęzi lokalnych i przełączanie się między nimi jest prostą operacją. Dzięki używaniu gałęzi możesz odróżniać od siebie zmiany. Aby utworzyć gałąź, uruchom to polecenie:

   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 workspace i nie jest uwzględniana w Gerricie 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ę:

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 najnowszej gałęzi wersji AOSP w Android Code Search, 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ż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 należy przestrzegać stylu kodu Java w AOSP dla współtwórcó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.

   • Podczas tworzenia interfejsów API należy przestrzegać wytycznych dotyczących interfejsów API Androida. Dzięki tym wytycznym możesz poznać kontekst decyzji dotyczących interfejsów API Androida. Dodatki i modyfikacje interfejsów API platformy są weryfikowane przez Metalava.

4. Tworzenie aplikacji na Androida.

5. Przetestuj kompilację.

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 wdrożyć zmiany:

1. Domyślnie Git rejestruje, ale nie śledzi wprowadzanych zmian. Aby polecić Gitowi śledzenie zmian, musisz je oznaczyć lub umieścić w etapie, aby uwzględnić je w zatwierdzeniu. Aby wprowadzić zmiany, 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 pojawi się prośba o podanie wiadomości zatwierdzenia.

3. Podaj komunikat zatwierdzenia w tym formacie:

   • Wiersz 1: nagłówek. Podaj jednowierszowe podsumowanie zmiany (maksymalnie 50 znaków). Rozważ użycie przedrostka do oznaczenia obszaru, który został zmieniony, a następnie dodaj opis zmiany wprowadzonej w tym commitie, 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 wiersze po 72 znakach. Opisz, jaki problem rozwiązuje ta zmiana i w jaki sposób. Chociaż treść jest opcjonalna, może być przydatna innym osobom, które muszą wrócić do zmiany. 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 zatwierdzenia 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 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. 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. Sugeruj właścicieli w 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.

   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ć zmiany do sprawdzenia.

Właściciele kodu sprawdzają zmiany w kodzie i w razie akceptacji wybierają zmiany i zgrywają je do gałęzi wewnętrznego rozwoju.

Określanie stanu zmiany

Aby określić stan plików w zmianie, sprawdź, czy obok nich znajdują się te ikony:

• done (ikona znacznika zaznaczenia): 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 uwzględnić opinię i wprowadzić poprawki:

1. Wykonaj czynności opisane w sekcji Wprowadzanie i testowanie zmian (kroki 2–4).

2. Aby wprowadzić poprawki, uruchom te 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 w drzewie źródłowym zostaną przesłane inne zmiany, które są sprzeczne z Twoimi, otrzymasz komunikat o konflikcie. Aby rozwiązać konflikty:

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

   repo sync .

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

2. Jeśli automatyczne uaktualnienie bazy danych nie powiedzie się, wykonaj uaktualnienie ręczne:

   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 poprawieniu plików powodujących konflikt uruchom to polecenie, aby zastosować nowe zatwierdzenia:

   git rebase --continue

Prześlij zmianę

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

Po zintegrowaniu przesłanych danych możesz przejść do panelu ciągłej integracji Androida, aby sprawdzić, kiedy przesłane dane zostaną zintegrowane z drzewem.