Процесс предложений для I2P | Proposals

Обзор

Этот документ описывает, как изменить спецификации 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.
Примечания о производительности и масштабируемости: Если функция будет иметь эффект на производительность (в ОЗУ, CPU, пропускной способности) или масштабируемости, должна быть некоторая аналитика того, насколько значительным будет этот эффект, чтобы мы могли избежать действительно дорогих регрессий производительности и чтобы мы могли избежать тратить время на незначительные выгоды.
Ссылки: Если предложение ссылается на внешние документы, они должны быть перечислены.

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

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

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

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

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