Отправьте патчи

На этой странице описан полный процесс отправки исправления в проект Android с открытым исходным кодом (AOSP), в том числе порядок запроса проверки и отслеживания изменений с помощью Gerrit . Gerrit — это веб-система проверки кода для проектов, использующих Git. Геррит поощряет более централизованное использование Git, позволяя всем авторизованным пользователям отправлять изменения, которые автоматически объединяются, если они проходят проверку кода. Кроме того, Gerrit упрощает просмотр, отображая изменения рядом в браузере и позволяя добавлять встроенные комментарии.

Предварительные условия

Для начала убедитесь, что вы выполнили следующее:

Ресурсы

Настроить Git

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

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

Аутентификация на сервере

Если вы делитесь IP-адресом с другими пользователями, квоты могут быть активированы даже для обычных шаблонов использования. Это может произойти, например, когда многие пользователи синхронизируют новых клиентов с одного и того же IP-адреса в течение короткого периода времени. Доступ с проверкой подлинности использует отдельную квоту для каждого пользователя независимо от IP-адреса. Подробнее об активации доступа с проверкой подлинности см. в разделе Использование аутентификации .

Запустить ветку репо

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

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

Изменить описания

  • Строка 1: Заголовок

    Предоставьте краткое описание в одну строку ( максимум 50 символов).

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

    ui: Removes deprecated widget

  • Строка 2: пусто

    Всегда оставляйте эту строку пустой.

  • Строка 3: Тело

    Напишите более подробное описание, начиная с этой строки.

    Это должно быть жестко обернуто максимум в 72 символа. Опишите, какую проблему решает изменение и как. Хотя это необязательно при реализации новых функций, другим будет очень полезно позже, если они обратятся к этому изменению, особенно для отладки.

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

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

Вот пример сообщения о фиксации:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

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

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

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

repo sync

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

Если автоматическое перебазирование не удалось, выполните перебазирование вручную.

repo rebase

Еще один инструмент для решения конфликта перебазирования — git mergetool . После успешного объединения конфликтующих файлов выполните следующую команду:

git rebase --continue

После завершения автоматического или ручного перебазирования запустите repo upload , чтобы отправить перебазированный патч.

После одобрения заявки

После того, как отправленное изменение проходит процесс рассмотрения и проверки, Геррит автоматически объединяет изменение в общедоступный репозиторий. Другие пользователи могут запустить repo sync , чтобы загрузить обновление в свои локальные клиенты.

Для добывающих проектов

Android использует ряд других проектов с открытым исходным кодом, таких как ядро ​​Linux и WebKit, как описано в разделе «Управление программным обеспечением Android ». Для большинства проектов, находящихся в каталоге external/ , внесите изменения в исходную версию, а затем сообщите специалистам по сопровождению Android о новой основной версии, содержащей ваши изменения.

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

Интересным частным случаем является Bionic. Большая часть кода взята из BSD, поэтому, если изменения не касаются кода, нового для Bionic, внесите исправление в исходную версию, а затем извлеките совершенно новый файл из соответствующей BSD.

Ядро Android

Внесите все изменения вверх по течению. Общие рекомендации см. в Руководстве по созданию ядра Android и на странице «Разработка кода ядра для GKI» .

отделение интенсивной терапии

Внесите все изменения в проект ICU в каталог external/icu (папки icu4c/ и icu4j/ ) на домашней странице ICU-TC . Дополнительную информацию см. в разделе «Отправка ошибок ICU и запросов на добавление функций» . Добавьте метку «android» ко всем восходящим запросам Jira.

КЛДР

Большая часть лингвистических данных в ICU поступает из проекта Unicode CLDR . Отправьте все запросы в восходящем направлении в соответствии с разделом «Вклад в CLDR» и добавьте метку «android».

LLVM/Clang/Компилятор-rt

Внесите все изменения в проекты, связанные с LLVM ( external/clang , external/compiler-rt , external/llvm ) на странице инфраструктуры компилятора LLVM .

мкш

Внесите все изменения в проект MirBSD Korn Shell по адресу external/mksh , отправив электронное письмо на адрес miros-mksh в домене mirbsd.org (для отправки туда подписка не требуется) или на Launchpad .

OpenSSL

Внесите все изменения в проект OpenSSL по external/openssl на странице OpenSSL .

V8

Отправьте все изменения в проект V8 по адресу external/v8 на странице выпуска V8 . Подробности см. в разделе «Вклад в V8» .

Вебкит

Внесите все изменения в проект WebKit по external/webkit на странице WebKit . Начните процесс с регистрации ошибки WebKit . В сообщении об ошибке используйте Android в полях «Платформа» и «ОС» , только если ошибка характерна для Android. Ошибки с гораздо большей вероятностью привлекут внимание рецензентов после добавления предложенного исправления и включения тестов. Подробности см. в разделе «Внесение кода в WebKit» .

zlib

Внесите все изменения в проект zlib по адресу external/zlib на домашней странице zlib .

,

На этой странице описан полный процесс отправки исправления в проект Android с открытым исходным кодом (AOSP), в том числе порядок запроса проверки и отслеживания изменений с помощью Gerrit . Gerrit — это веб-система проверки кода для проектов, использующих Git. Геррит поощряет более централизованное использование Git, позволяя всем авторизованным пользователям отправлять изменения, которые автоматически объединяются, если они проходят проверку кода. Кроме того, Gerrit упрощает просмотр, отображая изменения рядом в браузере и позволяя добавлять встроенные комментарии.

Предварительные условия

Для начала убедитесь, что вы выполнили следующее:

Ресурсы

Настроить Git

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

git config --global user.name Your Name
git config --global user.email your_email@gmail.com
    

Аутентификация на сервере

Если вы делитесь IP-адресом с другими пользователями, квоты могут быть активированы даже для обычных шаблонов использования. Это может произойти, например, когда многие пользователи синхронизируют новых клиентов с одного и того же IP-адреса в течение короткого периода времени. Доступ с проверкой подлинности использует отдельную квоту для каждого пользователя независимо от IP-адреса. Подробнее об активации доступа с проверкой подлинности см. в разделе Использование аутентификации .

Запустить ветку репо

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

repo start NAME .

You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and isn't included either on Gerrit or in the final source tree.

Make your change

Modify the source files, and test your changes.

For any changes made, follow License header best practices.

Commit your change

Commit the changes to your local repository with these commands:

git add -A
git commit -s

Изменить описания

  • Строка 1: Заголовок

    Предоставьте краткое описание в одну строку ( максимум 50 символов).

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

    ui: Removes deprecated widget

  • Строка 2: пусто

    Всегда оставляйте эту строку пустой.

  • Строка 3: Тело

    Напишите более подробное описание, начиная с этой строки.

    Это должно быть жестко обернуто максимум в 72 символа. Опишите, какую проблему решает изменение и как. Хотя это необязательно при реализации новых функций, другим будет очень полезно позже, если они обратятся к этому изменению, особенно для отладки.

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

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

Вот пример сообщения о фиксации:

Line 1, Headline - a short description

Line 3, Body - Add the detailed description of your patch here. Use as many lines
as needed. You can write an overall description, then list specifics.

I6e3c64e7a:Added a new widget.
I60c539a8f:Fixed the spinning image.
To read a blog about good commit descriptions (with examples), see How to Write a Git Commit Message by Chris Beams.

Upload to Gerrit

After you commit your change to your personal history, upload it to Gerrit with this command:

repo upload

If you started multiple branches in the same repository, you're prompted to select which ones to upload.

After a successful upload, Repo provides you with the URL of a new page on Gerrit. Click the link that Repo gives you to view your patch on the review server, add comments, or request specific reviewers for your patch.

Request a review

After you've uploaded your changes to Gerrit, the patch must be reviewed and approved by the appropriate code owners. Locate code owners in OWNERS files.

To find the appropriate code owners and add them as reviewers for your change, follow these steps.

  1. Select the SUGGEST OWNERS link in the Gerrit UI to see a list of code owners for the files in your patch.

    suggest owners link in Gerrit
    Figure 1. Suggest owners link in Gerrit
  2. Add code owners from the list as reviewers for your patch.

To determine the status of the files in your patch, check for the following icons next to the files in the patch.

  • (checkmark icon): Approved by code owner
  • (cross icon): Not approved by code owner
  • (clock icon): Pending approval by code owner
Figure 2. Example of files with icons showing code owner approval status

Upload a replacement patch

Suppose a reviewer looked at your patch and requested a small modification. You can amend your commit within Git, which results in a new patch on Gerrit that has the same change ID as the original.

git add -A
git commit --amend

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

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

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

repo sync

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

Если автоматическое перебазирование не удалось, выполните перебазирование вручную.

repo rebase

Еще один инструмент для решения конфликта перебазирования — git mergetool . После успешного объединения конфликтующих файлов выполните следующую команду:

git rebase --continue

После завершения автоматического или ручного перебазирования запустите repo upload , чтобы отправить перебазированный патч.

После одобрения заявки

После того, как отправленное изменение проходит процесс рассмотрения и проверки, Геррит автоматически объединяет изменение в общедоступный репозиторий. Другие пользователи могут запустить repo sync , чтобы загрузить обновление в свои локальные клиенты.

Для добывающих проектов

Android использует ряд других проектов с открытым исходным кодом, таких как ядро ​​Linux и WebKit, как описано в разделе «Управление программным обеспечением Android ». Для большинства проектов, находящихся под external/ , внесите изменения в исходную версию, а затем сообщите специалистам по сопровождению Android о новой основной версии, содержащей ваши изменения.

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

Интересным частным случаем является Bionic. Большая часть кода взята из BSD, поэтому, если изменения не касаются кода, нового для Bionic, внесите исправление в исходную версию, а затем извлеките совершенно новый файл из соответствующего BSD.

Ядро Android

Внесите все изменения вверх по течению. Общие рекомендации см. в Руководстве по созданию ядра Android и на странице «Разработка кода ядра для GKI» .

отделение интенсивной терапии

Внесите все изменения в проект ICU в каталог external/icu (папки icu4c/ и icu4j/ ) на домашней странице ICU-TC . Дополнительную информацию см. в разделе «Отправка ошибок ICU и запросов на добавление функций» . Добавьте метку «android» ко всем восходящим запросам Jira.

КЛДР

Большая часть лингвистических данных в ICU поступает из проекта Unicode CLDR . Отправьте все запросы в восходящем направлении в соответствии с разделом «Вклад в CLDR» и добавьте метку «android».

LLVM/Clang/Компилятор-rt

Внесите все изменения в проекты, связанные с LLVM ( external/clang , external/compiler-rt , external/llvm ) на странице инфраструктуры компилятора LLVM .

мкш

Внесите все изменения в проект MirBSD Korn Shell по адресу external/mksh , отправив электронное письмо на адрес miros-mksh в домене mirbsd.org (для отправки туда подписка не требуется) или на Launchpad .

OpenSSL

Внесите все изменения в проект OpenSSL по external/openssl на странице OpenSSL .

V8

Отправьте все изменения в проект V8 по адресу external/v8 на странице выпуска V8 . Подробности см. в разделе «Вклад в V8» .

Вебкит

Внесите все изменения в проект WebKit по external/webkit на странице WebKit . Начните процесс с регистрации ошибки WebKit . В сообщении об ошибке используйте Android в полях «Платформа» и «ОС» , только если ошибка характерна для Android. Ошибки с гораздо большей вероятностью привлекут внимание рецензентов после добавления предложенного исправления и включения тестов. Подробности см. в разделе «Внесение кода в WebKit» .

zlib

Внесите все изменения в проект zlib по адресу external/zlib на домашней странице zlib .