Clean-room на практике

mcrs строит поведение игры по описаниям этого поведения и никогда по коду игры. Здесь объясняется, кто что может читать, что может лежать в репозитории и как быть, если вы уже читали код игры. Страница простыми словами пересказывает docs/clean-room.md. Правило задает тот файл, поэтому если страница с ним расходится, прав файл.

Две работы делают два человека

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

	Автор спецификации	Исполнитель
Результат	Файл в docs/spec/	Код, тесты, заметки по дизайну
Может читать	Любой источник, в том числе код игры	docs/spec/, публичную документацию о том, что видит игрок, артефакты, выданные игрой, и тот код этого репозитория, который разрешают правила
Не должен	Переносить в спецификацию форму кода игры	Читать декомпилированный, деобфусцированный или размеченный маппингами код игры

“Артефакты, выданные игрой” - это датапак, отчеты в assets/mcrs/reports/, захваченные пакеты, сохранения и вывод tools/vanilla-oracle. Такой вывод служит свидетельством, и parity-тест сравнивает с ним наш результат.

Спецификация описывает поведение, то есть входы, выходы, порядок, время и константы в виде данных. Имен классов, методов, полей и переменных в ней нет, структуры функций тоже.

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

Если вы читали код игры

Многие разработчики под Paper и Fabric каждый день читают декомпилированный код игры. Если вы читали код игры про какое-то поведение, своими руками писать код этого поведения здесь нельзя. Внести вклад в него все равно можно, и для этого есть два пути.

Первый путь: вы пишете спецификацию, а код по ней пишет второй человек.

Второй путь: роль исполнителя вы отдаете ИИ-агенту. Это единственное исключение из правила, что один человек не берет обе роли, и у него два условия:

1. Вы читаете спецификацию и проверяете, что она верна.
2. Вы следите, чтобы у агента не было доступа к коду игры или его фрагментам. Проверьте его файлы, промпт и инструменты. Агент работает с теми же источниками, что и любой исполнитель.

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

Зачем нужны эти предосторожности

У всех этих правил одна цель. Они нужны, чтобы никто случайно не скопировал код или алгоритмы оригинальной игры или ее модификаций.

Если не уверены, читали ли вы код про какое-то поведение, скажите об этом в issue.

Чего в репозитории нет

Правило относится к коду, комментариям, тестам, заметкам по дизайну, сообщениям коммитов и issue. Ни в одном из этих мест нет трех вещей:

• Имен классов, методов и полей кода игры.
• Текста, который называет код портом, транскрипцией или зеркалом кода игры. Не пишите “port of” в коммите или документе.
• Теста, инструмента или скрипта, который читает код игры.

Несколько имен из кода игры сообщество использует как обычные термины, и они разрешены везде: ResourceKey, TagKey, BlockPos, SectionPos, ColumnPos и PalettedContainer. Новое имя попадает в этот список только после ревью.

Публичные API других проектов, таких как Paper, Bukkit, Velocity и Minestom, называть можно, потому что это не код игры.

По метке происхождения видно, насколько доверять правилу

У каждого правила в спецификации есть метка происхождения, она сообщает, откуда правило взялось. Например, source_suggested значит, что автор прочитал эталонное поведение и записал только поведение. Когда эксперимент с игрой подтверждает правило, метка меняется на подтвержденную. По метке читатель решает, насколько правилу можно доверять. Метки определены в docs/spec/registry.md, в разделе 0.3.

Генерация мира - исключение

Код генерации мира остается как есть и сохраняет свою историю. Исключение покрывает крейты mcrs_minecraft_worldgen*, mcrs_minecraft_biome и crates/mcrs_minecraft_vanilla_worldgen/ вместе с их заметками по дизайну. Новая работа в этих местах идет по обычным правилам, а изменение, которое задевает там имя из игры, это имя убирает.

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

Новому поведению нужны две issue

1. Первая issue просит спецификацию, и автор пишет ее в docs/spec/.
2. Вторая issue просит реализацию и ссылается на ID правил.
3. Исполнитель работает по спецификации. Вопрос уходит автору, а ответ попадает в спецификацию, чтобы следующий читатель нашел его там, а не в чате.

Дальше: формат спецификации описан на странице Спецификации и parity-тесты.