Отправить изменения кода

На этой странице описывается полный процесс отправки изменения кода в Android Open Source Project (AOSP), включая порядок запроса проверки и отслеживания изменений.

AOSP использует Gerrit — веб-систему проверки кода для проектов, использующих Git.

Подпишите лицензионные соглашения с авторами

Прежде чем вносить какие-либо изменения кода для AOSP, вам необходимо прочитать лицензионные соглашения и заголовки участников и подписать одно из следующих соглашений:

• Как индивидуальный участник, вносящий вклад только от своего имени, подпишите Лицензионное соглашение индивидуального участника .
• Если вы работаете в корпорации, убедитесь, что ваша компания подписала Лицензионное соглашение корпоративного участника, разрешающее вам вносить взносы от ее имени.

Начать ветку

Для каждого изменения кода, которое вы собираетесь внести, выполните следующие шаги:

1. Создайте новую ветку в соответствующем репозитории Git. Ветка — это не копия исходных файлов, а указатель на конкретный коммит, что упрощает создание локальных веток и переключение между ними. Используя ветки, вы можете идентифицировать изменения друг относительно друга. Выполните эту команду, чтобы создать ветку:

   repo start BRANCH_NAME

   Вы можете одновременно создать несколько независимых веток в одном репозитории. Ветка BRANCH_NAME находится локально в вашем рабочем пространстве и не включена ни в Gerrit, ни в окончательное дерево исходного кода. Ветки также привязаны к текущему проекту, поэтому, если вам нужно изменить файлы в разных проектах в рамках одного изменения, вам понадобится ветка в каждом проекте, где вы изменяете файлы.

2. (необязательно) Убедитесь, что ветка была создана:

   repo status .

   Вы должны увидеть только что созданную ветку. Например:

   project frameworks/native/                      branch mynewbranch

Внесите и протестируйте свои изменения

Чтобы внести и протестировать изменения, выполните следующие действия:

1. Чтобы убедиться, что вы работаете с самой актуальной кодовой базой, выполните синхронизацию всей кодовой базы:

   repo sync

   Если во время синхронизации возникли конфликты, см. шаги 2–4 в разделе Разрешение конфликтов синхронизации .

2. Найдите код, который нужно изменить. Чтобы найти код, воспользуйтесь поиском кода Android . С помощью поиска кода Android можно просмотреть исходный код AOSP в том виде, в котором он будет выглядеть при фактическом использовании. Подробнее см. в разделе «Начало работы с поиском кода» . Чтобы просмотреть весь код в последней версии AOSP в поиске кода Android, перейдите по ссылке https://cs.android.com/android/platform/superproject/ .

3. Измените или добавьте исходные файлы. Для любых внесённых изменений:

   • Определите, нужно ли использовать флаги запуска функций , и если да, реализуйте их в своем новом коде.

   • Следуйте рекомендациям в разделе Включение заголовков лицензий .

   • Для кода Java следуйте стилю кода AOSP Java для авторов .

   • Некоторые части AOSP написаны на Kotlin ( .kt ), и вы можете использовать Kotlin в тех областях платформы, где он уже реализован. Подробнее о Kotlin в Android см. в руководстве по стилю Kotlin для разработчиков Android и руководстве по взаимодействию Kotlin-Java . Более подробное руководство по Kotlin см. на сайте языка Kotlin .

   • При написании API следуйте рекомендациям Android API Guidelines . Эти рекомендации помогут вам понять контекст решений Android в отношении API. Дополнения и изменения в API платформы проверяются компанией Metalava .

4. Сборка Android .

5. Проверьте свою сборку .

Подготовьте и зафиксируйте свои изменения

Коммит — это базовая единица контроля версий в Git, представляющая собой снимок структуры каталогов и содержимого файлов всего проекта. Чтобы зафиксировать изменения, выполните следующие действия:

1. По умолчанию Git регистрирует, но не отслеживает вносимые вами изменения. Чтобы Git отслеживал ваши изменения, необходимо пометить их или добавить в коммит. Выполните эту команду, чтобы добавить изменение в коммит:

   git add -A

   Эта команда отслеживает изменения, внесенные вами в любые файлы.

2. Возьмите файлы из области подготовки и зафиксируйте или сохраните их в локальной базе данных:

   git commit -s

   По умолчанию открывается текстовый редактор и предлагается ввести сообщение о фиксации.

3. Предоставьте сообщение о фиксации в следующем формате:

   • Строка 1: Заголовок. Опишите изменение одной строкой (максимум 50 символов). Рекомендуется использовать префиксы для описания области, которую вы изменили, а затем добавить описание изменения, внесённого в этом коммите, например, как в следующем примере, содержащем изменение пользовательского интерфейса:

     ui: Removes deprecated widget
     

   • Строка 2: Пустая строка. После заголовка добавьте пустую строку.

   • Строка 3: Текст. Введите подробное описание длиной не более 72 символов (с жестким переносом). Опишите, какую проблему решает изменение и как. Хотя текст необязателен, он будет полезен тем, кому потребуется вернуться к изменению. Обязательно включите краткое примечание о любых предположениях или дополнительной информации, которая может быть важна, когда другой участник будет работать над этой функцией.

   Чтобы прочитать блог о хороших описаниях коммитов (с примерами), см . How to Write a Git Commit Message .

4. Сохраните коммит.

Уникальный идентификатор изменения, ваше имя и адрес электронной почты, указанные во время repo init , автоматически добавляются в сообщение о фиксации.

Загрузите изменение для проверки

После того, как вы внесете изменения в свою личную историю Git, загрузите их в Gerrit:

1. Выполните следующую команду, чтобы загрузить все ваши коммиты во все ваши проекты:

   repo upload

   Все изменения во всех проектах включены в загрузку.

   Вам будет предложено запустить скрипты-перехватчики.

2. Нажмите a , а затем Enter .

   Вам будет предложено одобрить загрузку:

   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. Нажмите y , а затем Enter , чтобы одобрить загрузку.

Вы должны получить сообщение, похожее на remote: SUCCESS .

Запросить отзыв

После успешной загрузки Repo предоставит вам ссылку на ваши изменения в Gerrit. Щелкните по ссылке, чтобы просмотреть изменения на сервере рецензирования, добавить комментарии или запросить рецензентов для вашего изменения. Все изменения в коде должны быть проверены соответствующими владельцами кода.

Чтобы запросить обзор:

1. В Gerrit нажмите ПРЕДЛОЖИТЬ ВЛАДЕЛЬЦЕВ :

   

   Рисунок 1. Ссылка «Предложить владельцам» в Gerrit.

   Откроется диалоговое окно рецензента. В этом диалоговом окне содержится список владельцев кода, которые могут проверить ваше изменение.

2. Нажмите на владельца кода, чтобы добавить его в свой отзыв.

   Кнопка ОТПРАВИТЬ активирована.

3. (Необязательно) Введите адрес электронной почты другого лица, которое должно просмотреть ваши изменения.

4. Нажмите ОТПРАВИТЬ , чтобы отправить изменение на рассмотрение.

Владельцы кода проверяют ваши изменения в коде и, если они приняты, выбирают изменения и объединяют их с внутренней веткой разработки.

Определить статус изменения

Чтобы определить статус файлов в вашем изменении, проверьте наличие следующих значков рядом с файлами в изменении:

• done (значок галочки): одобрено владельцем кода
• clear (значок крестика): не одобрен владельцем кода
• access_time (значок часов): Ожидает одобрения владельцем кода

На следующем рисунке показаны эти значки статуса, примененные к файлам при изменении:

Рисунок 2. Пример файлов со значками, показывающими одобрение владельца кода.

Устраните неполадку и загрузите заменяющее изменение

Если рецензент запрашивает внесение изменений в ваше обновление, вы можете внести поправки в свою фиксацию в Git, что приведет к созданию нового набора исправлений для того же изменения.

Чтобы разрешить обратную связь и внести изменения:

1. Выполните шаги 2–4 в разделе Внесение и тестирование изменений .

2. Чтобы внести изменения, выполните следующие команды:

   git add -A
   git commit --amend

3. Загрузите ваши изменения .

При загрузке исправленного изменения оно заменяет оригинал как на Gerrit, так и в вашей локальной истории Git.

Разрешение конфликтов синхронизации

Если в исходное дерево внесены другие изменения, конфликтующие с вашими, вы получите сообщение о наличии конфликтов. Чтобы разрешить конфликты:

1. Убедитесь, что вы работаете с самой последней версией кода:

   repo sync .

   Команда repo sync извлекает обновления с исходного сервера, а затем пытается автоматически перебазировать ваш HEAD на новый удаленный HEAD .

2. Если автоматическое перемещение не удалось, выполните ручное перемещение:

   repo rebase .

3. Разрешение конфликтов слияния. Если у вас нет предпочитаемого метода разрешения конфликтов слияния, вы можете использовать git mergetool для ручного устранения конфликтов между файлами.

4. После успешного исправления конфликтующих файлов выполните следующую команду, чтобы применить новые изменения:

   git rebase --continue

Внести изменения

После того как отправленное изменение пройдет процесс проверки и верификации, владелец кода отправит его вам либо в ветку, в которой было проверено изменение, либо во внутреннюю ветку.

После объединения ваших заявок вы можете посетить панель управления Android Continuous Integration, чтобы отслеживать, как ваши заявки интегрируются в дерево.