JEP 369: Migrate to GitHub

Аннотация

Размещать Git-репозитории сообщества OpenJDK на GitHub. Вместе с JEP 357 (Migrate from Mercurial to Git) это перенесло бы на GitHub все проекты OpenJDK с одним репозиторием, включая как выпуски JDK типа Feature Release (функциональный выпуск), так и выпуски обновлений JDK для версий 11 и более поздних.

Цели

• Разместить все Git-репозитории OpenJDK по адресу https://github.com/openjdk/.
• Выполнять проверки перед коммитом (jcheck) перед каждым push.
• Интегрировать существующие сервисы OpenJDK.
• Обеспечить несколько способов взаимодействия с GitHub.
• Обеспечить поддержку рабочих процессов, структурно похожих на существующие рабочие процессы на основе электронной почты и webrev.
• Сохранять и архивировать все метаданные.
• Обеспечить, чтобы сообщество OpenJDK всегда могло перейти к другому провайдеру хостинга исходного кода.
• Не требовать от разработчиков установки специфичных для OpenJDK инструментов, чтобы они могли вносить вклад.
• Не менять OpenJDK Bylaws.
• Не менять OpenJDK Census.

Что не является целью

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

Критерии успеха

• Значительно более быстрые clone и pull
• Более высокая доступность (время безотказной работы) репозиториев
• Возможность работать с репозиториями на GitHub через рассылки OpenJDK
• Возможность работать с репозиториями на GitHub через инструменты командной строки
• Возможность работать с репозиториями на GitHub через веб-браузеры

Мотивация

Мотивация этого JEP разделена на две части. Сначала мы рассматриваем, почему сообществу OpenJDK было бы выгодно использовать внешнего провайдера хостинга исходного кода, а затем объясняем, почему GitHub на данный момент лучший выбор провайдера.

Почему внешний провайдер хостинга исходного кода?

Внешний провайдер хостинга исходного кода — это сервис репозиториев исходного кода, который не реализуется и не управляется участниками сообщества OpenJDK. Примеры внешних провайдеров: BitBucket, GitLab, Phacility, SourceForge и GitHub.

Есть три основные причины, по которым сообществу OpenJDK стоит использовать внешнего провайдера хостинга исходного кода:

• Производительность. Многие провайдеры, если не все, обеспечивают отличную производительность — не только в отношении скорости сети, но и в отношении доступности, то есть времени безотказной работы. Для сообщества OpenJDK это означало бы значительно более быстрые clone и pull, а также более высокую доступность репозиториев исходного кода.

• API. Техническая причина размещать репозитории OpenJDK на платформе хостинга исходного кода — получить доступ к веб-API, через которые программы могут взаимодействовать с разработчиками на этой платформе. Хотя и сегодня этого можно добиться, взаимодействуя с разработчиками по электронной почте, реализовать программы, разбирающие произвольный текст писем, значительно сложнее, чем использовать структурированный API. Если программы могут участвовать в процессе ревью, становится возможной мощная автоматизация; несколько примеров приведено в разделе Описание.

• Расширение сообщества. Крупнейшие провайдеры также дали бы сообществу OpenJDK возможность привлечь большие существующие сообщества разработчиков и потенциальных участников. Если у разработчика уже есть учётная запись у провайдера, то, чтобы вносить вклад в OpenJDK, ему потребуется лишь несколько дополнительных шагов. Почти все open-source-проекты в более широком Java-сообществе размещены у внешних провайдеров, включая несколько дистрибутивов OpenJDK. Если репозитории OpenJDK тоже будут размещены у того же провайдера, это может способствовать ещё более тесному сотрудничеству.

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

Ещё одно соображение — то, как переход к внешнему провайдеру повлиял бы на рабочий процесс существующих участников. О том, как с помощью API платформ хостинга исходного кода можно поддержать несколько рабочих процессов, в том числе как можно сохранить почти весь существующий рабочий процесс сообщества OpenJDK, см. раздел Описание.

Почему GitHub?

Мотивация выбора GitHub в том, что он превосходен по всем трём основным причинам выбора внешнего провайдера. Производительность GitHub не хуже или выше, чем у других провайдеров, это крупнейший в мире сервис хостинга исходного кода (50 миллионов пользователей на май 2020 года), и у него один из самых обширных API.

Благодаря обширному API GitHub поддерживается во многих инструментах, включая текстовые редакторы, IDE, инструменты командной строки и графические настольные клиенты. GitHub поддерживают следующие текстовые редакторы (то есть разработчик может создавать pull request, проводить их ревью и комментировать их прямо из текстового редактора):

• Emacs (плагин magit + плагин forge)
• VS Code (плагин GitHub Pull Request)
• Atom (встроенная поддержка)

Работу с pull request на GitHub поддерживают следующие интегрированные среды разработки (IDE):

• IntelliJ (встроенная поддержка)
• Eclipse (GitHub Mylyn Connector)
• Visual Studio (GitHub Extension)

Есть также клиент командной строки hub (с открытым исходным кодом) и несколько графических настольных клиентов, например SourceTree, Tower и GitHub Desktop (с открытым исходным кодом).

Есть много других отличных провайдеров хостинга исходного кода. О том, почему это важно и почему это позволяет нам рекомендовать GitHub, см. раздел Риски и допущения.

Описание

Интересная часть перехода к внешнему провайдеру хостинга исходного кода состояла бы не в загрузке самих репозиториев в сервис: с учётом работы, проделанной в JEP 357 (Migrate from Mercurial to Git), это тривиально.
Интересно то, как переход к внешнему провайдеру повлиял бы на рабочий процесс участников OpenJDK.

Сегодня участники OpenJDK взаимодействуют через рассылки, отправляют изменения в Mercurial-репозитории, тестируют изменения через сервис jdk/submit и заводят отчёты об ошибках в JDK Bug System (JBS). Участники также могут пользоваться несколькими инструментами командной строки (CLI), прежде всего jcheck, webrev и defpath. Многим опытным участникам этот рабочий процесс нравится, и они считают его продуктивным. Поэтому при переходе к внешнему провайдеру крайне важно сохранить как можно большую часть этого рабочего процесса.

Рабочий процесс на GitHub и у других популярных провайдеров хостинга основан на понятии pull request (PR), который в общих чертах похож на письма с запросом на ревью (RFR), которые участники OpenJDK используют сегодня. Участник на GitHub создаёт PR из исходной ветки в целевую ветку определённого репозитория (исходная и целевая ветки не обязаны находиться в одном репозитории). Затем другие участники проводят ревью PR, и в ответ на замечания рецензентов в исходную ветку добавляются новые коммиты. Когда рецензенты довольны изменениями, PR сливается в целевую ветку.

Этот JEP предлагает поддерживать несколько рабочих процессов с помощью инструментов, разработанных в проекте Skara. Участники смогут выбрать тот рабочий процесс, который им больше всего подходит:

• На основе CLI и рассылок (похож на текущий рабочий процесс)
• На основе веб-браузера (через сайт GitHub)
• На основе текстового редактора и IDE (через плагины и поддержку GitHub в текстовых редакторах и IDE)
• На основе CLI (через специальные инструменты командной строки)

Разумеется, разные рабочие процессы можно смешивать и сочетать. В таком большом и разнообразном open-source-сообществе, как OpenJDK, единственное, что объединяет рабочие процессы отдельных участников, — то, что они различаются. Прежде чем описывать различные инструменты и сервисы, начнём с примера рабочего процесса для включения нового изменения. (Рабочие процессы для более специализированных задач, таких как синхронизация между репозиториями или добавление тегов, будут рассмотрены в будущих редакциях этого JEP.)

Рабочий процесс

Общее для всех четырёх рабочих процессов то, что каждое изменение начинается с pull request (PR). PR можно создать разными способами — из CLI, в веб-браузере, в текстовом редакторе или в IDE. Однако для создания PR нужна учётная запись на GitHub. От участников, не желающих создавать учётную запись на GitHub, мы продолжим принимать патчи, отправленные в рассылки OpenJDK. Однако для таких патчей потребуется, чтобы PR создал участник с учётной записью на GitHub — так же, как сегодня многие участники помогают новичкам создавать webrev и загружать их на cr.

После создания PR коммиты в нём анализирует инструмент анализа коммитов jcheck, который работает как серверная программа (так называемый «бот»). Бот jcheck использует API внешнего провайдера, чтобы показывать возможные проблемы в виде комментариев или ошибок, в зависимости от возможностей API провайдера. На GitHub бот jcheck, в частности, использует Checks API, чтобы выдавать информативные сообщения об ошибках. Бот jcheck настраивается через конфигурационный файл .jcheck/config в репозитории. Если это настроено, одна из проверок убеждается, что для предлагаемого изменения есть соответствующая задача в JBS. В этом случае бот проверяет, что заголовок PR соответствует заголовку задачи JBS, аналогично заголовкам писем RFR. Если в качестве заголовка PR указана задача JBS, бот jbs добавляет в соответствующую задачу JBS ссылку на PR.

Когда PR проходит jcheck, он получает метку "rfr". Это показывает потенциальным рецензентам, что PR теперь готов к ревью. (Рецензентам нет смысла заниматься изменением, которое даже не проходит jcheck.) В этот момент PR также автоматически получает метки в соответствии с областями исходного кода, которые меняются коммитами в PR. Например, PR в ветку master репозитория jdk с изменениями и в каталоге make, и в каталоге src/hotspot получает метки build-dev и hotspot-dev. Автоматически сгенерированное письмо RFR отправляется в рассылки build-dev@openjdk.java.net и hotspot-dev@openjdk.java.net, а также в любые другие рассылки, указанные автором PR. Письмо RFR содержит заголовок и текст PR, автоматически сгенерированную сводку коммитов в PR и ссылки на автоматически сгенерированные webrev.

Теперь рецензенты могут обсуждать изменения в PR, используя несколько рабочих процессов:

• Отвечая на письмо RFR, отправленное в рассылку (рассылки); в этом случае содержимое ответов копируется в PR на GitHub (учётная запись GitHub не требуется);
• Используя инструмент ревью на https://github.com/ через веб-браузер;
• Используя инструмент ревью в различных текстовых редакторах и IDE, интегрированных с GitHub;
• Используя графическое настольное приложение, интегрированное с GitHub; или
• Используя инструменты командной строки Skara.

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

Если автор PR по замечаниям рецензентов отправляет в исходную ветку дополнительные коммиты, бот отправляет ответ на письмо RFR, включающий автоматическую сводку нового коммита (коммитов) и автоматически сгенерированные инкрементальный и полный webrev.

Когда рецензенты удовлетворены изменениями, они отмечают PR как прошедший ревью. Это можно сделать:

• С помощью веб-браузера и https://github.com/,
• С помощью git pr approve из командной строки,
• С помощью текстового редактора и/или IDE с интеграцией GitHub или
• С помощью графического настольного инструмента с интеграцией GitHub.

Когда все рецензенты удовлетворены, автор PR наконец может интегрировать PR. Для этого он добавляет комментарий ровно с текстом /integrate, после чего происходит ряд действий:

1. Бот объединяет (сжимает) все коммиты в один коммит.
2. При необходимости бот перебазирует объединённый коммит на вершину целевой ветки (обычно master).
3. Бот составляет сообщение для итогового коммита, которое включает:
   • название PR в качестве заголовка сообщения коммита,
   • текст на основе комментария из PR, который начинается со слова /summary,
   • имена пользователей OpenJDK всех рецензентов, добавленные в трейлер Reviewed-by:, и
   • всех соавторов, добавленных в трейлеры Co-authored-by:.
4. Бот отправляет получившийся коммит в целевую ветку (обычно master).

Автор может заранее посмотреть, к чему приведёт команда /integrate, в том числе сообщение коммита, до того как PR будет действительно интегрирован.

Если автор PR не является Committer в OpenJDK, то после того как автор оставил команду /integrate в комментарии, добавляется метка sponsor. Затем Committer OpenJDK должен ввести команду /sponsor в новом комментарии, чтобы интегрировать PR.

Права доступа и роли

Как отмечалось ранее, мы не предлагаем менять OpenJDK Census, и роли и права доступа участников OpenJDK не будут воспроизводиться на внешней платформе хостинга исходного кода. Вместо этого серверные инструменты («боты») хранят соответствие между идентификаторами пользователей GitHub участников OpenJDK (не именами пользователей, которые могут меняться) и именами пользователей OpenJDK. В результате боты могут проверить, например, является ли автор PR Author в OpenJDK или является ли рецензент PR Reviewer в OpenJDK. Эта модель не зависит от внешнего провайдера. Кроме того, это значит, что не нужно дублировать данные OpenJDK Census у внешнего провайдера.

Инструменты

Участники проекта Skara разработали для поддержки этого JEP различные инструменты: как CLI-инструменты, которые работают локально на компьютере участника, так и серверные инструменты («боты»), которые работают на серверах провайдеров. CLI-инструменты в первую очередь предназначены для участников, которые хотят работать с внешним провайдером из командной строки. Это следующие инструменты:

• git-fork: создать форк проекта у внешнего провайдера и клонировать его
• git-pr: обновить, одобрить, загрузить, показать и т. д. pull request
• git-sync: синхронизировать ветки из вышестоящего репозитория
• git-publish: опубликовать локальную ветку в удалённом репозитории
• git-info: извлечь информацию, специфичную для OpenJDK, из сообщения коммита
• git-token: взаимодействовать с менеджером учётных данных Git для работы с токенами
• git-proxy: направлять весь сетевой трафик команды Git через HTTP(S)-прокси -git-skara: узнать о CLI-инструменте Skara и обновить его

Следующие CLI-инструменты уже были предоставлены для поддержки JEP 357 (Migrate from Mercurial to Git):

• git-jcheck: запустить jcheck локально
• git-webrev: создать webrev
• git-defpath: настроить пути для push и pull
• git-translate: преобразовать хэши hg в хэши git и обратно

Боты, которые помогают участникам:

• pr: проверяет pull requests, ставит на них метки и интегрирует их
• ml-bridge: передаёт комментарии между рассылками и сервисами хостинга исходного кода
• notify: отправляет уведомления в рассылки после push
• archiver: архивирует все метаданные PR в формате JSON в Git-репозитории
• forwarder: пересылает отправленные коммиты в другие репозитории (например, в песочницу)
• jbs: обновляет JBS (аналогично существующему сервису «hgupdater»)
• submit: пример тестового сервиса, реализованного в виде бота

Сервисы

Помимо ботов, есть два сервиса, которые помогают участникам и рецензентам:

• Сервис OCA избавляет рецензентов от необходимости проверять, подписали ли участники Oracle Contributor Agreement.

• Тестовый сервис — обобщённая версия репозитория jdk/submit. Он позволяет участнику отправить запрос /test в комментарии к PR, на который могут ответить один или несколько тестовых сервисов. Простой пример тестового сервиса уже доступен в виде бота submit.

Альтернативы

• Продолжать использовать Mercurial и существующий процесс работы OpenJDK. (Для репозиториев такого размера, как репозитории JDK, мы не ожидаем, что будет практично использовать hg-git или похожие инструменты, чтобы поддерживать клиентскую версию Mercurial для серверного основного Git-репозитория.)

• Использовать GitLab EE в качестве внешнего провайдера хостинга исходного кода.

• Использовать BitBucket в качестве внешнего провайдера хостинга исходного кода.

Тестирование

• Почти все сценарии процессов работы реализованы в виде интеграционных тестов в проекте Skara.

• Проект Skara долгое время использовал предлагаемый процесс работы для своего собственного кода.

• Несколько других проектов OpenJDK перенесли свои репозитории на GitHub в порядке оценки: OpenJFX, Loom, Mobile, OpenJMC, Panama, Metropolis, Valhalla, Amber, Tsan, ZGC, Lanai и некоторые из проектов Code Tools. Эти проекты обеспечили проверку инструментов, ботов и сервисов в реальных условиях, чтобы дальнейшие переходы проектов проходили с минимальными трудностями.

Риски и допущения

Основной риск перехода к внешнему провайдеру хостинга исходного кода состоит в том, что сообщество OpenJDK может стать зависимым от этого провайдера. Сами данные системы контроля версий всегда будут независимы от провайдера благодаря распределённой природе Git. Однако есть риск, что метаданные, например комментарии код-ревью, окажутся привязаны к конкретному провайдеру. Есть также риск, что инструменты и процессы работы станут зависеть от конкретного провайдера, так что сменить провайдера будет невозможно из-за допущений, заложенных в инструменты.

Снижение этих рисков было одной из главных задач проекта Skara. Следующие проектные решения гарантируют, что важные метаданные не будут привязаны к какому-либо конкретному провайдеру:

• Все обсуждения в pull requests дублируются в соответствующие рассылки OpenJDK.

• Все обсуждения в pull requests архивируются в двух форматах: mbox (для чтения людьми) и JSON (для обработки программами).

• Уведомления о push отправляются в соответствующие рассылки *-changes@openjdk.java.net, что позволяет не зависеть от RSS-лент провайдера.

• Для организации пользователей и уровней привилегий используется OpenJDK Census, что позволяет не зависеть от инструментов провайдера для организации пользователей.

• Домен https://git.openjdk.java.net/ перенаправляет к текущему провайдеру хостинга исходного кода сообщества OpenJDK. URL исходного кода, записанные в задачах JBS и сообщениях рассылок, используют этот домен, а не домен текущего провайдера.

Чтобы инструменты Skara не зависели от API конкретного провайдера, поддержка нескольких внешних провайдеров с самого начала была строгим требованием. Кроме того, все инструменты должны работать с открытой GitLab Community Edition (GitLab CE).

Зависимости

• JEP 296: Consolidate the JDK Forest into a Single Repository
• JEP 357: Migrate from Mercurial to Git