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

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

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

Подпишите лицензионные соглашения для участников

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

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

Примечание. Чтобы внести изменения в исходные проекты, используемые Android, вам необходимо внести их непосредственно в этот проект. Дополнительную информацию см. в разделе «Внесение вклада в вышестоящие проекты» .

Открыть ветку

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

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

   repo start BRANCH_NAME
   

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

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

   repo status .
   

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

   project frameworks/native/                      branch mynewbranch
   

   Примечание. Вы также можете использовать repo branches для получения списка всех ветвей, где текущей ветке (если таковая имеется) предшествует звездочка (*).

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

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

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

   repo sync
   

   Примечание. Чтобы просто синхронизировать текущий проект, добавьте точку (.) к команде repo sync : repo sync . . Синхронизация текущего проекта выполняется быстрее, чем синхронизация всего репозитория.

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

2. Найдите код, который нужно изменить. Чтобы найти код, рассмотрите возможность использования Android Code Search . Вы можете использовать Android Code Search, чтобы просмотреть исходный код AOSP в том виде, в котором вы его фактически используете. Дополнительные сведения см. в разделе Начало работы с поиском кода . Чтобы просмотреть весь код в main ветке при поиске кода Android, перейдите по адресу https://cs.android.com/android/platform/superproject/main .

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

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

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

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

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

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

4. Сборка Андроида .

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

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

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

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

   git add -A
   

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

   Примечание. Если вы просто хотите отслеживать изменения в определенном файле, используйте git add filename .
   Примечание. Помимо отслеживания изменений в файлах, git add можно использовать для выполнения других операций, таких как промежуточное изменение и удаление файлов.

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

   git commit -s
   

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

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

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

     ui: Removes deprecated widget
     

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

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

   Чтобы прочитать блог о хороших описаниях коммитов (с примерами), см. раздел «Как написать сообщение о коммите Git» .

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

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

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

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

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

   repo upload
   

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

   Примечание. Чтобы загрузить изменения только в текущем проекте, добавьте точку (.) к команде repo upload : repo upload . .
   Примечание. Если вы работаете над изменением, требующим внесения изменений в файлы в нескольких проектах, используйте тему в Gerrit, чтобы связать изменения вместе, независимо от того, используете ли вы repo upload или repo upload . . Тема Gerrit гарантирует, что изменения сохраняются вместе в целях предварительного тестирования и автоматического слияния. Дополнительную информацию см. в разделе «Использование тем».

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

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

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

   Upload project frameworks/native/ to remote branch main:
   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. Нажмите на владельца кода, чтобы добавить его в свой обзор.

   Примечание. Чтобы понять, как определяются владельцы, обратитесь к бэкэнду find-owners .

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

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

4. (Необязательно) Нажмите +1 рядом с надписью «Автоматическая отправка», чтобы автоматически отправить изменение после получения одобрения. Если вы не нажмете эту кнопку, сотрудник Google должен будет внести изменения за вас.

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

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

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

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

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

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

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

Устраните отзыв и загрузите заменяющее изменение

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

Примечание. Если вы создали другие ветки и сделали другие фиксации после загрузки изменения, вы, скорее всего, будете работать в ветке одного из этих коммитов, а не в ветке исходного изменения. Таким образом, прежде чем вы сможете разрешить обратную связь для исходной ветки, вы должны перейти к этой ветке с помощью команды repo start EXISTING_BRANCH_NAME .

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

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
   

Отправить изменение

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

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