av
863769406f
Имя `.pm.json` пережило плагин `av-dev-pm` на два месяца и указывало в пустоту. Правило, которое из этого вынуто: имя служебного файла — имя плагина, который его завёл, и по нему же владельца узнают. - `docs/.pm.json` → `docs/.docs.json`, запись 13 журнала. Прежнее имя docs.py не читает намеренно: по этому числу upgrade решает, какие записи применять, и два дома разъехались бы молча ровно там, где это дороже всего. Вместо совместимости — узнавание: check видит старый файл и печатает готовую git mv - у каталога задач появилась своя версия формата — ключ `tasks` в `.tasks.json`, свой журнал версий и своё повышение. До сих пор её не было вовсе, хотя docs.py в комментарии уверенно на неё ссылался: описание опережало механику ровно так, как сказано в решении 195 - число своё, а не копия канонического: плагин ставится в одиночку, и у проекта без docs/ версии канона нет — сверять было бы не с чем - конфиг задач стал обязательным (init и adopt apply пишут его всегда), check сверяет число, `check --fix` его не приписывает: приписанное объявляло бы каталог приведённым к формату, шагов которого никто не делал - переезды 11 и 12 в новый журнал задним числом не переписаны — версия 1 велит догнать формат по журналу канона, называя признаки отставания поимённо (каталог в docs/tasks/, живой SPRINT.md) - запись 60 в DECISIONS со следствиями 200–203; отдельно разведено с решением F, где `.docs.json` отвергался как указатель путей: отвергнут был указатель, а не имя
62 lines
5.2 KiB
Markdown
62 lines
5.2 KiB
Markdown
# Журнал версий формата задач
|
|
|
|
Одна запись на версию. Проект знает свою версию из ключа `tasks` в `<каталог
|
|
задач>/.tasks.json`; повышение (`upgrade` в [SKILL.md](../SKILL.md), раздел
|
|
«Версия формата») идёт по записям снизу вверх от версии проекта до текущей и
|
|
делает то, что в них названо.
|
|
|
|
Правило записи: **что добавилось, что переехало, что удалено, что сделать
|
|
проекту**. Без последнего пункта запись бесполезна — по ней и работает
|
|
повышение.
|
|
|
|
Версия — целое число. Обратной совместимости у формата нет: есть «приведён» и «не
|
|
приведён».
|
|
|
|
**Это журнал формата задач, а не канона документов.** Числа у них разные и
|
|
двигаются порознь: плагин `av-dev-tasks` ставится в одиночку, и у проекта без
|
|
`av-dev-docs` версии канона нет вовсе. Журнал канона —
|
|
`references/changelog.md` скилла `av-dev-docs:canon`.
|
|
|
|
---
|
|
|
|
## Версия 1 — 2026-08-11
|
|
|
|
Первая объявленная версия формата. До неё каталог задач версии не имел вовсе:
|
|
формат менялся, а сказать, к какому его состоянию приведён конкретный проект,
|
|
было нечем — `tasks.py` о расхождении молчал, и отставший каталог выглядел
|
|
здоровым ровно до первой команды, которая об него спотыкалась.
|
|
|
|
**Что появилось.** Ключ `tasks` в `<каталог задач>/.tasks.json` — целое число,
|
|
версия формата. Сам файл стал **обязательным**: до сих пор он заводился только
|
|
ради имён, отличных от умолчания, и проект с умолчаниями жил без него. Версия —
|
|
не настройка, от которой можно отказаться, поэтому `init` и `adopt apply` теперь
|
|
пишут файл всегда, а `check` требует числа и сверяет его со своим.
|
|
|
|
**Что версия значит, а что нет.** Она отвечает на один вопрос — «по какой записи
|
|
журнала повышать каталог». Что записи применены **по существу**, из числа не
|
|
следует: двигают его руками, и соврать им так же легко, как любой другой
|
|
строкой. `check --fix` недостающее число не приписывает намеренно — это было бы
|
|
объявлением каталога приведённым к формату, шагов которого никто не делал.
|
|
|
|
**Чего в этой записи нет.** Переезды, случившиеся до появления числа, — каталог
|
|
из `docs/` в корень (канон 11) и отмена спринтов (канон 12) — задним числом сюда
|
|
не переписаны. Они уже названы журналом канона, и второй перечень тех же шагов
|
|
разошёлся бы с первым. Версия 1 — это формат на день её появления, что бы
|
|
проекту ни пришлось пройти до неё.
|
|
|
|
**Что сделать проекту.**
|
|
|
|
1. **Догнать формат по журналу канона, если каталог отстал.** Признаки известны
|
|
поимённо: каталог лежит в `docs/tasks/` (канон 11 велит `git mv docs/tasks
|
|
tasks` и починку относительных ссылок внутри записей), в нём есть `SPRINT.md`
|
|
или теги `sprint:<слаг>` (канон 12 велит снести файл, вернуть строки в беклог
|
|
через `check --fix` и расставить порядок грумингом). Ничего из этого нет —
|
|
каталог уже в сегодняшнем формате, и шаг пропускается.
|
|
2. **Завести `<каталог задач>/.tasks.json`**, если его нет. Имена частей в него
|
|
не переписываются: там только то, что отличается от умолчания.
|
|
3. **Записать версию**: `"tasks": 1` первым ключом.
|
|
4. `tasks.py check --dir <каталог задач>` — до отсутствия расхождений.
|
|
|
|
**Что при этом не трогается.** Записи в `items/`, индексы и `REJECTED.md` не
|
|
меняются ни строкой: версия 1 объявляет то, что уже есть, а не переделывает его.
|