темы: определение, объявление в шапке и манифест набора
- тема — набор правил об одном фокусе разработки, имя латиницей (нижний 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:
@@ -9,7 +9,7 @@ code in this repository.
|
||||
|
||||
Канон конвенций разработки для личных проектов. Сами конвенции лежат в
|
||||
`conventions/{arch,lang/<язык>,stack/<стек>}/`; обвязка канона (`README.md`,
|
||||
`LANGUAGE.md`, `GUIDE.md`, `prefixes.toml`, `conv`) живёт в корне и в
|
||||
`LANGUAGE.md`, `GUIDE.md`, `manifest.toml`, `conv`) живёт в корне и в
|
||||
репозитории-потребители не едет.
|
||||
|
||||
Ниже — короткие инварианты с идентификаторами; детали и обоснования в
|
||||
@@ -60,18 +60,27 @@ code in this repository.
|
||||
действия.
|
||||
- Модальность принадлежит правилу, а не файлу: `status:` в шапке отменён.
|
||||
|
||||
## Идентификаторы и префиксы
|
||||
## Идентификаторы: тема и префикс
|
||||
|
||||
- Тема — набор правил об одном фокусе разработки и единица подписки. Имя —
|
||||
латиницей, рекомендуется нижний kebab-case, годится любой идентификатор,
|
||||
пригодный для имени файла.
|
||||
- META-28: тема объявлена в шапке (`topic: time`) и стоит в манифесте набора
|
||||
(`manifest.toml`, секция `[topics.live]`). Слои одной темы несут одно имя —
|
||||
по нему собираются в один файл, как бы ни назывались их файлы; имя файла
|
||||
повторяет тему из удобства.
|
||||
- META-29: имя темы не переиспользуется, снятое уходит в `[topics.retired]`
|
||||
с причиной и датой. Оно живёт в `origin:` копий и в подписках манифестов.
|
||||
- Формат `<ПРЕФИКС>-<номер>`, нумерация сквозная внутри файла. Порядок правил
|
||||
в файле — по читаемости: номер это идентификатор, а не позиция.
|
||||
- Идентификаторы не переиспользуются. Удалённое правило оставляет дыру, новое
|
||||
берёт следующий свободный номер, а не первый освободившийся.
|
||||
- Новый файл конвенции — новый префикс: четыре заглавные латинские буквы,
|
||||
уникальные по всему канону, выбираются под файл, а не выводятся по формуле.
|
||||
Объявляется в шапке (`prefix: KEYS`) и регистрируется в `prefixes.toml`,
|
||||
секция `[live]`, путём от корня репозитория.
|
||||
- Удаление или разделение файла: префикс уходит в `[retired]` с причиной и
|
||||
датой, а не освобождается.
|
||||
Объявляется в шапке (`prefix: KEYS`) и регистрируется в манифесте набора,
|
||||
секция `[prefixes.live]`, путём от корня репозитория.
|
||||
- Удаление или разделение файла: префикс уходит в `[prefixes.retired]` с
|
||||
причиной и датой, а не освобождается.
|
||||
- Префиксы на букву `X` канон не занимает: они зарезервированы за локальными
|
||||
правилами репозиториев-потребителей.
|
||||
- Перенос правила в другой файл — смысловое изменение: новый префикс и новый
|
||||
@@ -121,13 +130,12 @@ code in this repository.
|
||||
|
||||
## Оформление файла
|
||||
|
||||
Шапка `prefix:` (плюс `extends:`) → `# Тема` → вводная проза → отдельным
|
||||
абзацем строка о версии языка (её точный текст — в `LANGUAGE.md`, раздел
|
||||
«Ссылка на язык из конвенции») → `## Область действия` (обязателен для
|
||||
трудноизменяемых слоёв — META-11) → правила → `## Связано`, если
|
||||
канонические ссылки есть (META-17; пустого раздела не заводят). Имя файла —
|
||||
kebab-case по теме. Проза
|
||||
переносится по ~76 колонок; таблицы и блоки кода не переносятся.
|
||||
Шапка `topic:` и `prefix:` (плюс `extends:`) → `# Тема` → вводная проза →
|
||||
отдельным абзацем строка о версии языка (её точный текст — в `LANGUAGE.md`,
|
||||
раздел «Ссылка на язык из конвенции») → `## Область действия` (обязателен для
|
||||
трудноизменяемых слоёв — META-11) → правила → `## Связано`, если канонические
|
||||
ссылки есть (META-17; пустого раздела не заводят). Имя файла повторяет имя
|
||||
темы. Проза переносится по ~76 колонок; таблицы и блоки кода не переносятся.
|
||||
|
||||
## Ревью формы
|
||||
|
||||
|
||||
Reference in New Issue
Block a user