темы: определение, объявление в шапке и манифест набора
- тема — набор правил об одном фокусе разработки, имя латиницей (нижний kebab-case рекомендуется, годится любой идентификатор, пригодный для имени файла); определение в LANGUAGE.md и README.md - заведены META-28 и META-29: тема объявляется в шапке (`topic:`), стоит в манифесте набора и не переиспользуется; `topic:` добавлен во все 12 файлов - prefixes.toml и topics.toml слиты в manifest.toml — манифест набора против манифеста подключения `.conventions.toml`, разделы topics/prefixes с live и retired
This commit is contained in:
@@ -32,11 +32,11 @@ prefix: META
|
||||
|
||||
## Оформление
|
||||
|
||||
Имя файла — kebab-case по теме: `app-directories.md`. Правилом это не
|
||||
Имя файла повторяет имя темы: `app-directories.md`. Правилом это не
|
||||
записано, и это случай META-25: регуляркой имя проверяется тривиально, но
|
||||
обоснование сводится к «чтобы имя файла в реестре префиксов писалось одним
|
||||
способом» — вреда от нарушения нет, значит и высшей модальности нет, а на
|
||||
СЛЕДУЕТ такое правило не окупает строчку.
|
||||
вреда от нарушения нет — тема объявлена в шапке (META-28), и сборка идёт по
|
||||
объявленному имени, а не по имени файла. Значит, и высшей модальности нет, а
|
||||
на СЛЕДУЕТ такое правило не окупает строчку.
|
||||
|
||||
## Канон и копии
|
||||
|
||||
@@ -68,6 +68,30 @@ prefix: META
|
||||
дорого: перенос правила в другой файл — это новый префикс и новая
|
||||
нумерация, поэтому после разреза все внешние ссылки обходят руками.
|
||||
|
||||
### META-28. Тема объявляется в шапке файла и стоит в манифесте набора
|
||||
|
||||
**ДОЛЖЕН.** Шапка несёт ключ `topic:` с именем темы, и это имя стоит в
|
||||
манифесте набора.
|
||||
|
||||
**ПОЧЕМУ.** Тема — единица подписки и единица сборки: потребитель перечисляет
|
||||
темы в своём манифесте, а сборщик складывает в один файл все слои темы. Пока
|
||||
имя выводится из имени файла, у сборщика нет способа узнать, что два слоя,
|
||||
названные по-разному, — один документ; переименование файла при этом молча
|
||||
заводит новую тему, подписка перестаёт находить прежнюю, а ссылки «конвенция
|
||||
`logging`» в копиях остаются висеть. Объявленное имя вдобавок сверяется с
|
||||
манифестом — выведенное сверять не с чем.
|
||||
|
||||
### META-29. Имя темы не переиспользуется
|
||||
|
||||
**НЕ ДОЛЖЕН.** Снятое или переименованное имя темы другой теме не выдаётся:
|
||||
оно уходит в раздел выбывших манифеста с причиной и датой.
|
||||
|
||||
**ПОЧЕМУ.** Имя темы живёт в чужих репозиториях — в шапке `origin:` каждой
|
||||
копии, в подписке потребителя, в тексте ссылок. Выданное второй теме, оно
|
||||
начинает указывать на другой набор правил, и обнаруживается это не на сборке,
|
||||
а по содержанию: файл обновится штатно, изменится текст. Та же дисциплина и по
|
||||
той же причине действует для префиксов правил.
|
||||
|
||||
### META-2. Конвенция заводится, когда решение принимается третий раз
|
||||
|
||||
**СЛЕДУЕТ.** Поводом служит одно и то же решение, принятое третий раз и
|
||||
|
||||
Reference in New Issue
Block a user