Процесс предложений для I2P | I2P - Проект невидимого интернета

Обзор

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

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

Это информационный документ.

Мотивация

Ранее наш процесс обновления спецификаций I2P был относительно неформальным: мы вносили предложение на форуме разработчиков и обсуждали изменения, потом достигали консенсуса и вносили в спецификацию проект изменений (не обязательно в этом порядке), и в конце концов реализовывали изменения.

У этого процесса было несколько проблем.

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

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

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

Как теперь изменять спецификации

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

Как и в случае с RFC, каждое предложение получает номер. В отличие от RFC, предложения могут изменяться со временем, сохраняя тот же номер, до тех пор, пока они не будут окончательно приняты или отклонены. История каждого предложения будет храниться в репозитории сайта I2P.

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

(Этот процесс весьма похож на процесс улучшения Python, за исключением того, что предложения для I2P вновь интегрируются в спецификации после реализации, тогда как PEP становится новой спецификацией.)

Небольшие изменения

Все еще допустимо вносить небольшие изменения непосредственно в спецификацию, если код можно написать более или менее сразу, или косметические изменения, если в изменении кода нет необходимости. Этот документ отражает намерения текущих разработчиков, а не постоянное обязательство всегда использовать этот процесс в будущем: мы оставляем за собой право настолько вдохновиться, что можем броситься реализовывать что-то, топливом для чего станут ночь, кофеин или M&M’s.

Как добавляются новые предложения

Для подачи предложения разместите его на форуме разработчиков или создайте тикет с приложенным предложением.

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

Действующие редакторы предложений - zzz и str4d.

Что должно содержаться в предложении

Каждое предложение должно иметь заголовок с полями:

:author:
:created:
:thread:
:lastupdated:
:status:

Поле author должно содержать имена авторов предложения.
Поле thread должно быть ссылкой на тему форума разработчиков, где это предложение было изначально размещено, или на новую тему, созданную для обсуждения этого предложения.
Поле lastupdated изначально должно быть равно полю created, и должно обновляться всякий раз, когда предложение изменяется.

Эти поля должны быть установлены при необходимости:

:supercedes:
:supercededby:
:editor:

Поле supercedes - это список, разделенный запятыми, всех предложений, которые заменяет это предложение. Эти предложения должны быть Отклонены, и в их поле supercededby должен быть установлен номер этого предложения.
Поле editor должно быть установлено, если в это предложение вносятся значительные изменения, которые не существенно изменяют его содержание. Если содержание изменяется существенно, следует добавить либо дополнительного author, либо создать новое предложение, замещающее это.

Эти поля не обязательны, но рекомендуются:

:target:
:implementedin:

Поле target должно описывать, в какой версии планируется реализовать предложение (если оно Открытое или Принятое).
Поле implementedin должно описывать, в какой версии предложение было реализовано (если оно Завершенное или Закрытое).

Тело предложения должно начинаться с раздела Обзор, объясняющего, о чем предложение, что оно делает и в каком состоянии оно находится.

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

Мотивация: Какую проблему стремится решить предложение? Почему эта проблема важна? Если возможно несколько подходов, почему избран именно этот?
Дизайн: Высокоуровневый обзор новых или модифицированных функций, как они работают, как взаимодействуют друг с другом и с остальной частью I2P. Это основная часть предложения. Некоторые предложения начинают только с Мотивации и Дизайна и ждут спецификации, пока Дизайн не будет примерно правильным.
Последствия для безопасности: Какие эффекты предлагаемые изменения могут оказать на анонимность, насколько хорошо они понимаются и так далее.
Спецификация: Подробное описание того, что нужно добавить в спецификации I2P для реализации предложения. Это должно быть так же подробно, как это будет содержаться в спецификациях: независимые программисты должны суметь написать совместимые реализации предложения, основываясь на его спецификациях.
Совместимость: Будут ли версии I2P, следуя этому предложению, совместимы с версиями, которые не делают этого? Если да, как будет достигнута совместимость? Обычно мы стараемся не терять совместимость, если это вообще возможно; мы не делали “поворотных” изменений с марта 2008 года и не хотим делать другое.
Реализация: Если предложение будет трудно реализовать в текущей архитектуре I2P, документ может содержать некоторое обсуждение того, как его реализовать. Фактические патчи должны быть на публичных ветвях monotone или загружены в Trac.
Примечания по производительности и масштабируемости: Если функция окажет влияние на производительность (в RAM, CPU, пропускной способности) или масштабируемость, должен быть проведен анализ на то, насколько значительное будет это влияние, чтобы можно было избежать действительно дорогих регрессий производительности и потратить время на незначительные выходы.
Ссылки: Если предложение ссылается на внешние документы, они должны быть указаны.

Статус предложения

Открытое: Предложение на обсуждении.
Принятое: Предложение завершено, и мы намерены реализовать его. После этого момента следует избегать существенных изменений в предложении и рассматривать их как знак того, что процесс дал где-то сбой.
Завершено: Предложение было принято и реализовано. После этого момента предложение не должно изменяться.
Закрыто: Предложение было принято, реализовано и включено в основные документы спецификации. После этого момента предложение не должно изменяться.
Отклонено: Мы не собираемся реализовывать функцию, описанную здесь, хотя можем сделать какую-то другую версию. См. комментарии в документе для получения подробностей. Предложение не должно изменяться после этого момента; чтобы поднять какую-то другую версию идеи, напишите новое предложение.
Черновик: Это еще не полное предложение; здесь явно не хватает частей. Пожалуйста, не добавляйте никаких новых предложений с этим статусом; поместите их в подкаталог “идеи”.
Требует-Доработки: Идея предложения хорошая, но у этого предложения в текущем виде есть серьезные проблемы, мешающие его принятию. См. комментарии в документе для получения подробностей.
Неактивно: Предложение долгое время не трогалось, и не похоже, что кто-то собирается завершить его в ближайшее время. Оно может снова стать “Открытым”, если получит нового сторонника.
Требуется-Исследование: Существуют исследовательские проблемы, которые нужно решить, прежде чем станет ясно, является ли предложение хорошей идеей.
Метаданные: Это не предложение, а документ о предложениях.
Запасное: Это предложение не является тем, что мы в настоящее время планируем реализовать, но возможно мы захотим воскресить его в будущем, если решим сделать что-то типа того, что оно предлагает.
Информационное: Это предложение является последним словом о том, что оно делает. Оно не станет спецификацией, если кто-то не захочет скопировать и вставить его в новую спецификацию для новой подсистемы.

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

Нумерация предложений

Номера 000-099 зарезервированы для специальных и мета-предложений. Сотый и выше используются для фактических предложений. Номера не перераспределяются.

Ссылки

Процесс предложений Tor