конфиг: одна версия и один служебный файл, .av-dev.toml в корне
Версий было две — канон 14 в docs/.docs.json и формат задач 1 в <каталог задач>/.tasks.json, — и порознь они двигались потому, что плагины ставились порознь. Плагин один, версия одна и начинается с 1; журналы обеих прежних нумераций закрыты и лежат рядом непереписанными, действующий журнал открывается записью о слиянии с перечнем шагов проекту. Формат TOML взят ради комментариев: файл живёт в репозитории проекта, и назначение числа читают из него самого. Отсюда правило записи — скрипты правят строку, а не переписывают файл. Читатель общий, shared/config.py: два разбора одной схемы были бы двумя домами. Каталог задач перестал узнаваться служебным файлом и называется ключом [tasks] dir; узнают его по индексу. Прежние файлы не читаются — увидев их, docs.py и tasks.py называют прежнюю раскладку и зовут upgrade.
This commit is contained in:
@@ -407,7 +407,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
|
||||
| 0 | сошлось / сделано | дальше по сценарию |
|
||||
| 1 | **только `check`:** найден дрейф индексов и файлов | `check --fix`, остаток разобрать |
|
||||
| 2 | ошибка употребления: аргументы или нарушенное правило | читать сообщение, это отказ по существу |
|
||||
| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `<каталог задач>/.tasks.json`, повтор не поможет |
|
||||
| 3 | окружение: каталог не найден, конфиг битый или мимо диска | чинится путём или `.av-dev.toml` в корне, повтор не поможет |
|
||||
| 4 | внутренний сбой | дефект скрипта, доложить |
|
||||
|
||||
Различать 1 и 3 обязательно: «дрейф в беклоге» — рабочая ситуация, «каталога
|
||||
@@ -494,38 +494,24 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
|
||||
[fix](references/task-fix.md) · [chore](references/task-chore.md) ·
|
||||
[research](references/task-research.md).
|
||||
|
||||
## Версия формата
|
||||
## Версия раскладки
|
||||
|
||||
Формат каталога задач меняется, и проект должен знать, к какой его версии
|
||||
приведён. Число живёт ключом `tasks` в `<каталог задач>/.tasks.json`, журнал
|
||||
версий — [references/changelog.md](references/changelog.md), сверяет их
|
||||
`tasks.py check`: отстало — строка расхождения, ушло вперёд — устарел плагин.
|
||||
Формат каталога задач меняется, и проект должен знать, к какой версии он
|
||||
приведён. Число живёт ключом `version` в `.av-dev.toml` в корне репозитория,
|
||||
журнал версий — [журнал скилла `doc-canon`](../doc-canon/references/changelog.md),
|
||||
сверяет их `tasks.py check`: отстало — строка расхождения, ушло вперёд — устарел
|
||||
плагин. Обратной совместимости нет: есть «приведён» и «не приведён».
|
||||
|
||||
**Версия своя, а не канона документов.** Плагин ставится в одиночку: проект,
|
||||
взявший учёт работ без `av-dev-docs`, каталога `docs/` не имеет вовсе, а значит
|
||||
не имеет и версии канона — сверять было бы не с чем. Обратной совместимости у
|
||||
формата нет: есть «приведён» и «не приведён».
|
||||
**Версия одна на всю раскладку — и на документы, и на задачи.** Своя у каталога
|
||||
задач была, пока плагинов было три и ставились они порознь: проект мог взять
|
||||
учёт работ без канона документов, и общее число оказалось бы домом, которого у
|
||||
половины проектов нет. Плагин один — довод ушёл, а два числа оставляли бы
|
||||
вопрос, по какому журналу повышать.
|
||||
|
||||
**`upgrade` — повысить каталог до текущего формата:**
|
||||
|
||||
1. `python3 $tk check --dir D` — первая же строка расхождений называет версию
|
||||
проекта и версию скрипта. Проект новее скрипта — **обнови маркетплейс**, а не
|
||||
проект: это отстал плагин.
|
||||
2. Иди по [журналу](references/changelog.md) снизу вверх от версии проекта до
|
||||
текущей и делай названное в каждой записи. Записи независимы и применяются по
|
||||
порядку.
|
||||
3. Подними `tasks` в `.tasks.json` до текущей — руками, последним шагом. Раньше
|
||||
времени поднятое число объявляет каталог приведённым к формату, шагов
|
||||
которого никто не делал; `check --fix` этого не пишет намеренно.
|
||||
4. `check --dir D` ещё раз — до отсутствия расхождений.
|
||||
|
||||
Записи журнала описывают **что сделать проекту**. Если запись этого не говорит —
|
||||
это дефект журнала, и о нём надо сказать, а не догадываться.
|
||||
|
||||
**Канон документов сюда не вмешивается.** Его журнал двигает своё число в
|
||||
`docs/.docs.json` и вправе сказать «позови этот скилл», но не двигать версию
|
||||
формата задач: две версии, ходящие по одному журналу, разъедутся на первом же
|
||||
проекте, где стоит один плагин без другого.
|
||||
**Повышает проект скилл `av-dev:doc-canon`, операция `upgrade`** — он идёт по
|
||||
журналу, двигает число и зовёт этот скилл там, где запись касается задач. Здесь
|
||||
повышения нет намеренно: две операции, двигающие одно число, разъезжаются на
|
||||
первом же проекте, где прошла только одна из них.
|
||||
|
||||
## Сценарии
|
||||
|
||||
@@ -689,19 +675,17 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
|
||||
действительно новый, а перевод чужой раскладки делает `av-dev:doc-canon`.
|
||||
У скрипта поиск вверх по дереву ещё жив — он для непереведённых проектов, и
|
||||
полагаться на него скилл не должен: молча найденный чужой каталог это дрейф.
|
||||
- **Версия формата и настройки живут в `<каталог задач>/.tasks.json`** — свой
|
||||
файл у своего плагина: ключ `tasks` с версией формата плюс **имена** файлов и
|
||||
заголовков, и последние — только если отличаются от умолчания. Неизвестный
|
||||
ключ — код 3 на любой команде, так что лишнее слово в этом объекте
|
||||
останавливает работу с задачами целиком.
|
||||
- **Версия и настройки живут в `.av-dev.toml` в корне репозитория** — версия
|
||||
ключом `version`, настройки каталога секцией `[tasks]`: `dir` — где каталог
|
||||
лежит, плюс **имена** файлов и заголовков, и последние только если отличаются
|
||||
от умолчания. Неизвестный ключ в секции — код 3 на любой команде, так что
|
||||
лишнее слово останавливает работу с задачами целиком.
|
||||
|
||||
Дом именно свой, а не `docs/.docs.json`, потому что `docs/` принадлежит
|
||||
плагину канона: проект, поставивший учёт работ без него, каталога `docs/` не
|
||||
имеет вовсе. Прежний ключ `tasks` в `docs/.pm.json` читается, **только когда
|
||||
своего файла нет** — для проектов, заведённых до раскола плагинов; скрипт при
|
||||
этом говорит замечанием, куда его перенести. Есть оба — побеждает свой, и об
|
||||
этом тоже говорится вслух: молча выбранный из двух конфиг это дрейф. Версию
|
||||
прежний дом не знает и знать не может — она читается только из своего файла.
|
||||
Дом в корне, а не внутри каталога задач, по двум причинам: настройка, лежащая
|
||||
внутри настраиваемого каталога, не смогла бы сказать, **где он**; и версия
|
||||
одна на весь плагин, а корень есть и у проекта без `docs/`. Прежние
|
||||
`<каталог задач>/.tasks.json` и `docs/.docs.json` не читаются — увидев их,
|
||||
скрипт говорит «прежняя раскладка» и зовёт `upgrade`.
|
||||
- **Секции беклога** берутся из заголовков `##` индекса как есть; их количество
|
||||
и названия — дело проекта (умолчание `Ядро` / `Инфра`). **В конфиге их нет** —
|
||||
второй список разошёлся бы с заголовками молча.
|
||||
|
||||
Reference in New Issue
Block a user