JEP 1: JDK Enhancement-Proposal & Roadmap Process

ПРИМЕЧАНИЕ. Большая часть этого документа заменена документом JEP 2.0 Process Proposal, согласно которому JEP создаются и ведутся как задачи особого типа «JEP» в JDK Bug System. Подробности см. в этом предложении. Со временем это предложение будет включено в данный документ.

Аннотация

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

Цели

Основная цель этого процесса — получать регулярно обновляемый список предложений, который служит долгосрочной Roadmap (дорожная карта) для проектов выпусков JDK (JDK Release Projects) и связанных работ. Roadmap должна охватывать не менее трёх лет вперёд, чтобы на исследование, определение и реализацию самых сложных предложений оставалось достаточно времени.

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

Этот процесс открыт для каждого участника OpenJDK с ролью Committer. Решения по конкретным предложениям будут приниматься прозрачно, но в конечном счёте остаются за OpenJDK Lead.

Этот процесс никоим образом не заменяет Java Community Process. JCP остаётся органом, управляющим всеми стандартными API Java SE и связанными интерфейсами. Если предложение, принятое в этот процесс, предполагает пересмотр существующих стандартных интерфейсов или определение новых, то параллельно в JCP должна быть проведена работа по проектированию, рассмотрению и утверждению этих изменений — либо в рамках Maintenance Review существующего JSR, либо в контексте нового JSR.

Обзор

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

• Она требует двух или более недель инженерной работы,

• Она вносит существенное изменение в JDK или в процессы и инфраструктуру его разработки, или

• На неё высокий спрос у разработчиков или клиентов.

JDK Roadmap — это список JEP, которые OpenJDK Lead признал кандидатами для текущих и будущих проектов выпусков JDK. JEP в Roadmap упорядочены с учётом их зависимостей от других JEP и предлагаемых дат начала, если они есть.

То, что конкретный JEP присутствует в Roadmap, означает лишь, что с технической точки зрения это официально зарегистрированное предложение. Нет никакой гарантии, что кто-либо будет над ним работать, и тем более — что его конечный результат войдёт в какой-либо проект выпуска JDK.

Кто над какими JEP будет работать, решают сами участники с ролью Committer, часто совместно с организациями, в которых они работают.

Group Lead, Area Lead и OpenJDK Lead должны удостовериться, что достаточно участников с ролью Committer и других участников взялись выполнить всю работу, необходимую для завершения JEP, чтобы его можно было считать обеспеченным ресурсами (funded). Эта работа включает не только проектирование и реализацию, но и, при необходимости, разработку тестов QA, разработку тестов TCK, документацию и любые другие действия, которые могут потребоваться.

Если JEP определяет возможность, которая должна быть интегрирована в JDK, то после того как он будет обеспечен ресурсами, OpenJDK Lead может назначить его в конкретный проект выпуска JDK.

Принятие решений и достижение консенсуса

В конечном счёте OpenJDK Lead решает, какие JEP принять для включения в Roadmap. Однако JDK — очень большая и сложная система, и ни один человек не может рассчитывать понимать каждую область и каждый компонент во всех подробностях на уровне эксперта. Поэтому при оценке поступающих предложений OpenJDK Lead опирается на подтверждённую экспертизу участников с ролями Reviewer, Group Lead и Area Lead.

ПРИМЕЧАНИЕ. «Area Lead» — не термин, определённый в предлагаемом уставе сообщества OpenJDK (OpenJDK Community Bylaws). Area Lead — это OpenJDK Members, у которых есть экспертиза и обязанности на уровне нескольких групп (Group). Их неформально назначает OpenJDK Lead.

Поэтому большая часть работы над успешным JEP будет состоять в достижении консенсуса по предложению: нужно убедить некоторых участников с ролью Reviewer рецензировать его, а некоторых Group Lead или Area Lead — одобрить его.

Этот процесс не предписывает какого-либо конкретного способа достижения этой цели. Тем не менее ожидается, что типичное новое предложение сначала появится как идея, которую неформально изучат и доработают в рамках конкретной группы (Group), затем будет оформлено как JEP для дальнейшего рассмотрения и комментариев, затем одобрено Group Lead этой группы, а позже соответствующим Area Lead, и после этого представлено на принятие OpenJDK Lead. Обсуждения по ходу обычно ведутся по электронной почте, но для особенно крупных или спорных предложений могут быть полезны встречи для рассмотрения. Результаты любых таких встреч следует сообщать в список обсуждения JEP, чтобы они были зафиксированы.

Одобрение JEP со стороны Group Lead или Area Lead задумано как достаточно весомое заявление. Его следует рассматривать как равнозначное заявлению «Я буду доказывать, что этот JEP нужно обеспечить ресурсами».

Когда участник с ролью Reviewer рецензирует JEP или когда Group Lead или Area Lead одобряет JEP, этот факт записывается в самом JEP. Список JEP, одобренных Group Lead, можно считать Roadmap этой группы, а список JEP, одобренных Area Lead, — Roadmap этой области (Area).

Безумные идеи

Этот процесс явно открыт для смелых, нестандартных и даже совершенно безумных идей. Такие идеи часто требуют значительных предварительных исследований, экспериментов и обсуждения в сообществе, прежде чем они будут готовы к предложению в качестве улучшений самого JDK. Доработку идеи можно вести в одном или нескольких исследовательских предложениях. Конечный результат исследовательского JEP — не работающий код в JDK, а задокументированное более глубокое понимание решаемой проблемы и пространства её решений, желательно с подробностями, достаточными для конкретного предложения по улучшению.

Состояния процесса

Успешный JEP проходит через следующие состояния:

• Draft (черновик) — автор распространяет его для первичного рассмотрения и достижения консенсуса

• Posted — автор внёс его в архив JEP для более широкого рассмотрения

• Submitted — автор объявил его готовым к оценке

• Candidate (кандидат) — OpenJDK Lead принял его для включения в Roadmap

• Funded — Group Lead или Area Lead признал его полностью обеспеченным ресурсами

• Completed — завершён и поставлен

Автор предложения может перевести его вперёд из Draft в Posted и из Posted в Submitted. Автор также может перевести его назад: из Funded в Candidate или Posted и из Candidate в Posted.

Автор предложения может перевести его из любого состояния, кроме Completed и Rejected, в

• Withdrawn — отозван автором; позднее может быть составлен заново

Group Lead, Area Lead или OpenJDK Lead может перевести предложение из Candidate в Funded и из Funded в Completed.

OpenJDK Lead может перевести предложение вперёд из Submitted в Candidate, а также из Submitted, Candidate или Funded в

• Rejected — признано идеей, которой не стоит заниматься, или идеей, у которой так мало шансов быть обеспеченной ресурсами, что держать её в Roadmap не имеет смысла

Долгоживущие информационные и процессные JEP (Informational и Process), такие как JEP, который вы сейчас читаете, могут находиться ещё в одном состоянии:

• Active — одобрен OpenJDK Lead для публикации

Формат предложения

Документы JEP пишутся простым текстом на языке облегчённой разметки Markdown. Их точный формат определён в JEP 2. Пример черновика JEP доступен здесь.

Общие данные о JEP записываются в начале файла в формате, похожем на RFC-822. Строки, перед которыми стоит «+», обязательны для подачи предложения. Строки заголовка подробно описаны в JEP 2, а здесь приведена краткая сводка:

+Title: <title>
+Author: <author's full name>
 Organization: <employer name>
+Created: YYYY/MM/DD
+Type: Feature | Research | Infrastructure | Process
 State: <see above>
+Exposure: Open | Closed
+Component: <area>/<component>
+Scope: SE | JDK | Implementation
 JSR: <number, if an active JSR>
 RFE: <number of primary RFE, if any> (<secondary RFE> ...)
+Discussion: <mailing-list address>
 Start: YYYY/QN
 Depends: <draft names or JEP numbers>
 Blocks: <draft names or JEP numbers>
 Effort: XS | S | M | L | XL
 Duration: XS | S | M | L | XL
+Template: 1.0

Эта строка добавляется или изменяется, когда участник с ролью Reviewer удовлетворён JEP:

Reviewed-by: <reviewer's full name>, ...

Эта строка добавляется или изменяется, когда Group Lead или Area Lead одобряет JEP:

Endorsed-by: <endorser's full name>, ...

Эта строка добавляется, когда предложение размещается в архиве:

JEP: <number>

Group Lead или Area Lead добавляет эту строку, переводя предложение в состояние Funded:

Funded-by: <org or individual name(s)>

Когда обеспеченное ресурсами предложение, описывающее возможность для проекта выпуска JDK, назначается в конкретный выпуск, OpenJDK Lead добавляет эту строку:

Release: <number>

Порядок работы

Архив JEP опубликован по адресу http://openjdk.java.net/jeps.

Чтобы подать JEP на размещение, отправьте заполненный шаблон по электронной почте, как вложение типа text/plain, на адрес jep dash submit at openjdk dot java dot net. Настоящий человек проверит ваш JEP на разумность, присвоит ему номер и разместит в архиве.

После того как ваш JEP размещён, вы можете обновлять его сами: клонируйте репозиторий JEP по адресу http://hg.openjdk.java.net/jep/jeps, отредактируйте его файл, сделайте коммит и затем отправьте (push) изменения. При коммите изменения в существующий JEP начинайте первую строку сообщения коммита с номера JEP без каких-либо дополнений, за которым следует двоеточие. Когда вы отправите изменение, серверный хук репозитория обновит затронутые общедоступные веб-страницы.

Например, чтобы исправить опечатку в гипотетическом JEP 42:

$ hg clone http://hg.openjdk.java.net/jep/jeps
destination directory: jeps
requesting all changes
adding changesets
adding manifests
adding file changes
added 54 changesets with 60 changes to 23 files
updating to branch default
23 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cd jeps
$ emacs jep-42.md ...
$ hg ci -m "42: Fix typo"
$ hg push ssh://hg.openjdk.java.net/jep/jeps
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 changes to 1 files
remote: snapshot taken
remote: changes published to http://openjdk.java.net/jeps
remote: notifying jep-changes@openjdk.java.net
$

Благодарности

Благодарим Brian Goetz, Paul Hohensee, Georges Saab, Dalibor Topic и Mikael Vidstedt за комментарии к черновикам этого документа. Благодарность также причитается сообществу Python, из процесса PEP которого были заимствованы многие полезные идеи.