Przesyłanie zmian kodu

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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, ale 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ć jednocześnie kilka niezależnych gałęzi. 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ł. 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 stosuj się do stylu kodu Java w AOSP dla autoró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ć zmianę, uruchom to polecenie:

   git add -A

   To polecenie śledzi zmiany wprowadzone w dowolnych plikach.

2. Pobierz 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 prefiksów do opisania zmienionego obszaru, a następnie dodaj opis wprowadzonej zmiany w tym komicie, np. w takim przykładzie, który zawiera zmianę interfejsu:

     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ść o zatwierdzeniu 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 commity 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 android15-qpr2-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 następnie 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 przyjęcia 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ć te 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 zmienione zmiany, zastąpią one oryginalne 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 wiadomość 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 przenieść bazę HEAD na nową odległą bazę 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 rozwiązaniu konfliktów w plikach uruchom to polecenie, aby zastosować nowe zatwierdzenia:

   git rebase --continue

Prześlij zmianę

Gdy przesłany kod przejdzie proces sprawdzania i weryfikacji, właściciel kodu prześle go do Ciebie na gałęzi, na której sprawdzano zmiany, 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.