язык: усиления источников названы своими
- три клетки «что взято» правились по факту: DMN даёт политику совпадения, но не требует полноты; в 29148 обоснование — рекомендуемый атрибут; вывод про обязательность шаблона в EARS не сформулирован - заведён раздел «Где источник усилен»: полнота таблиц, обязательность обоснования и вывод из EARS предъявлены как наши решения с доводами - поправлены два места, где та же натяжка повторялась прозой: «Таблицы решений» и «Обоснование обязательно»
This commit is contained in:
+33
-10
@@ -34,9 +34,9 @@ version: 1
|
|||||||
|---|---|---|
|
|---|---|---|
|
||||||
| **BCP 14** (RFC 2119 + RFC 8174) | шкала модальности; правило «нормативно только заглавное»; сдержанность в высшей модальности; англоязычный словарь как готовый | синонимы `REQUIRED`, `RECOMMENDED`, `OPTIONAL`; `SHALL` как форма требования |
|
| **BCP 14** (RFC 2119 + RFC 8174) | шкала модальности; правило «нормативно только заглавное»; сдержанность в высшей модальности; англоязычный словарь как готовый | синонимы `REQUIRED`, `RECOMMENDED`, `OPTIONAL`; `SHALL` как форма требования |
|
||||||
| **ISO/IEC Directives, Part 2** | разделение «требование — рекомендация — разрешение — возможность»; запрет модальных глаголов в утверждениях о факте | списки равнозначных словесных форм («is to», «is required to», «only … is permitted») |
|
| **ISO/IEC Directives, Part 2** | разделение «требование — рекомендация — разрешение — возможность»; запрет модальных глаголов в утверждениях о факте | списки равнозначных словесных форм («is to», «is required to», «only … is permitted») |
|
||||||
| **ISO/IEC/IEEE 29148** | обоснование как обязательный атрибут; единичность нормы; проверяемость; метод верификации отдельным атрибутом | остальной аппарат требований: приоритеты, источники, матрицы трассируемости |
|
| **ISO/IEC/IEEE 29148** | характеристики хорошего требования — единичность и проверяемость; обоснование и метод верификации как отдельные атрибуты требования | остальной аппарат требований: приоритеты, источники, матрицы трассируемости |
|
||||||
| **DMN** | таблица решений с объявленной политикой совпадения и требованием полноты | исполняемая семантика и всё, что предполагает движок решений |
|
| **DMN** | таблица решений с объявленной политикой совпадения | исполняемая семантика и всё, что предполагает движок решений |
|
||||||
| **EARS** | вывод о том, что выигрыш даёт жёсткий шаблон, а не его конкретный вид; паттерн «нежелательное поведение» — в виде таблицы | шаблоны как форма записи правила: `WHEN`, `WHILE`, `WHERE` |
|
| **EARS** | паттерн «нежелательное поведение» — в виде таблицы | шаблоны как форма записи правила: `WHEN`, `WHILE`, `WHERE` |
|
||||||
| **OpenSpec** | четырёхчастная форма правила; адресуемость правила идентификатором; форма «условие → следствие» для стыка правил | `SHALL`; `GIVEN/WHEN/THEN` как общая форма записи |
|
| **OpenSpec** | четырёхчастная форма правила; адресуемость правила идентификатором; форма «условие → следствие» для стыка правил | `SHALL`; `GIVEN/WHEN/THEN` как общая форма записи |
|
||||||
|
|
||||||
Три отклонения стоят объяснения, потому что выглядят как произвол.
|
Три отклонения стоят объяснения, потому что выглядят как произвол.
|
||||||
@@ -56,14 +56,37 @@ version: 1
|
|||||||
система, и её поведение разворачивается во времени: состояние, событие,
|
система, и её поведение разворачивается во времени: состояние, событие,
|
||||||
исход. У конвенции субъект — автор кода, и разворачивать нечего: есть
|
исход. У конвенции субъект — автор кода, и разворачивать нечего: есть
|
||||||
ситуация выбора и вердикт. Это таблица, а не траектория. Тем же рассуждением
|
ситуация выбора и вердикт. Это таблица, а не траектория. Тем же рассуждением
|
||||||
отклонены шаблоны EARS как форма записи правила, а взят из EARS другой
|
отклонены шаблоны EARS как форма записи правила, а взято из EARS другое —
|
||||||
результат: измеримый выигрыш дала там сама обязательность шаблона, а не его
|
сообщённое снижение числа дефектов после введения шаблонов. Вывод, что дело в
|
||||||
конкретная форма.
|
самой обязательности формы, а не в её конкретном виде, наш; он ниже, среди
|
||||||
|
усилений.
|
||||||
|
|
||||||
Исключение — стык правил, где субъект действительно система: там форма
|
Исключение — стык правил, где субъект действительно система: там форма
|
||||||
«условие → следствие» берётся сознательно, вместе со служебными словами под
|
«условие → следствие» берётся сознательно, вместе со служебными словами под
|
||||||
неё. Это единственное место, и оно описано в «Таблицах решений».
|
неё. Это единственное место, и оно описано в «Таблицах решений».
|
||||||
|
|
||||||
|
## Где источник усилен
|
||||||
|
|
||||||
|
Три решения идут дальше источника, и это наши решения, а не его требования.
|
||||||
|
Названы они отдельно, чтобы довод не подменялся ссылкой: спорить с ними нужно
|
||||||
|
по существу, а не со стандартом.
|
||||||
|
|
||||||
|
- **Обоснование обязательно.** В 29148 rationale — из списка рекомендуемых
|
||||||
|
атрибутов требования; обязательный костяк там другой, это характеристики
|
||||||
|
самого требования. Здесь правило без блока ПОЧЕМУ не принимается, потому что
|
||||||
|
конвенция живёт годами и переживает автора: норма без причины через год либо
|
||||||
|
отменяется первым возражением, либо соблюдается там, где вредит.
|
||||||
|
- **Полнота таблицы решений.** DMN даёт политику совпадения как именованный
|
||||||
|
атрибут, а полноты не требует: индикатор полноты был в первой версии
|
||||||
|
спецификации и из последующих убран, полноту проверяют валидаторы
|
||||||
|
инструментов. Здесь она требуется, потому что таблицу и заводят ради
|
||||||
|
видимости пропуска: неперечисленный случай в прозе не виден, а пустая
|
||||||
|
клетка видна.
|
||||||
|
- **Вывод про обязательность шаблона.** В EARS сообщается о снижении числа
|
||||||
|
дефектов в требованиях после введения шаблонов. Вывод, что выигрыш даёт сама
|
||||||
|
обязательность формы, а не её конкретный вид, — наш: он объясняет, почему мы
|
||||||
|
берём из EARS результат, но не берём сами шаблоны.
|
||||||
|
|
||||||
## Что даёт формализация
|
## Что даёт формализация
|
||||||
|
|
||||||
Адресуемое правило — не украшение формы, а условие работы трёх механизмов:
|
Адресуемое правило — не украшение формы, а условие работы трёх механизмов:
|
||||||
@@ -146,8 +169,8 @@ version: 1
|
|||||||
## Обоснование обязательно
|
## Обоснование обязательно
|
||||||
|
|
||||||
Правило без блока ПОЧЕМУ не принимается. Это требование к форме, а не
|
Правило без блока ПОЧЕМУ не принимается. Это требование к форме, а не
|
||||||
пожелание; в 29148 обоснование — атрибут требования наравне с самим
|
пожелание. В 29148 обоснование — отдельный атрибут требования, но из
|
||||||
требованием, и по тем же причинам:
|
рекомендуемых; здесь оно обязательно, и вот почему:
|
||||||
|
|
||||||
- **Обоснование — единственный способ увидеть, что правило устарело.**
|
- **Обоснование — единственный способ увидеть, что правило устарело.**
|
||||||
Норма стареет молча; причина стареет заметно. Когда причина отпала, видно,
|
Норма стареет молча; причина стареет заметно. Когда причина отпала, видно,
|
||||||
@@ -350,8 +373,8 @@ XMIG-2, XMIG-4 — МЕХАНИЗИРОВАНО: `internal/archrules`, в нов
|
|||||||
которой нумеруются как подпункты правила (`XLOG-8.1`).
|
которой нумеруются как подпункты правила (`XLOG-8.1`).
|
||||||
|
|
||||||
Таблица плотнее прозы и не даёт пропустить ветку: пустая клетка видна, а
|
Таблица плотнее прозы и не даёт пропустить ветку: пустая клетка видна, а
|
||||||
неупомянутый случай в абзаце — нет. Два свойства такой таблицы взяты из DMN,
|
неупомянутый случай в абзаце — нет. От такой таблицы требуются два свойства —
|
||||||
где они называются и проверяются:
|
первое названо в DMN, второе мы добавили сами («Где источник усилен»):
|
||||||
|
|
||||||
- **Политика совпадения.** По умолчанию строки взаимоисключающи: любой
|
- **Политика совпадения.** По умолчанию строки взаимоисключающи: любой
|
||||||
ситуации соответствует ровно одна. Если это не так, таблица объявляет
|
ситуации соответствует ровно одна. Если это не так, таблица объявляет
|
||||||
|
|||||||
@@ -4,31 +4,11 @@
|
|||||||
решения. Закрытый вопрос отсюда удаляется — принятое решение живёт в
|
решения. Закрытый вопрос отсюда удаляется — принятое решение живёт в
|
||||||
`README.md`, `GUIDE.md` или `LANGUAGE.md`, а не в этом файле.
|
`README.md`, `GUIDE.md` или `LANGUAGE.md`, а не в этом файле.
|
||||||
|
|
||||||
Две секции: сначала язык и подход, потом канон с тулингом. Пункт 1 пришёл
|
Две секции: сначала язык и подход, потом канон с тулингом.
|
||||||
из внешнего ревью описания языка и проверен по файлам на месте.
|
|
||||||
|
|
||||||
# Язык и подход
|
# Язык и подход
|
||||||
|
|
||||||
## 1. Натяжки в опоре на стандарты
|
## 1. Одиннадцать таблиц не прочитаны на взаимоисключительность
|
||||||
|
|
||||||
Три места, где источнику приписано чуть больше, чем в нём есть:
|
|
||||||
|
|
||||||
- **DMN и полнота таблицы.** Политика совпадения — действительно именованное
|
|
||||||
свойство DMN. Полноту стандарт не требует: индикатор полноты был в DMN 1.0
|
|
||||||
и убран в последующих версиях, её проверяют валидаторы инструментов.
|
|
||||||
- **29148 и обоснование.** Rationale там — рекомендуемый атрибут требования,
|
|
||||||
а не обязательный «наравне с самим требованием». Обязательный костяк
|
|
||||||
стандарта — характеристики well-formed requirement, откуда честно взяты
|
|
||||||
единичность и проверяемость.
|
|
||||||
- **EARS.** Вывод «выигрыш дала сама обязательность шаблона, а не его
|
|
||||||
конкретный вид» — экстраполяция, поданная как взятое из источника. Вывод
|
|
||||||
от этого не становится неверным, но графа «что взято» описывает не
|
|
||||||
содержимое EARS.
|
|
||||||
|
|
||||||
Остальное в таблице проверку выдержало, включая вторую половину `MAY` из
|
|
||||||
BCP 14 и списки эквивалентных словесных форм ISO Directives.
|
|
||||||
|
|
||||||
## 2. Одиннадцать таблиц не прочитаны на взаимоисключительность
|
|
||||||
|
|
||||||
`LANGUAGE.md` объявил, что строки таблицы решений взаимоисключающи по
|
`LANGUAGE.md` объявил, что строки таблицы решений взаимоисключающи по
|
||||||
умолчанию, а иной порядок объявляется явно. Объявление не делает таблицы
|
умолчанию, а иной порядок объявляется явно. Объявление не делает таблицы
|
||||||
@@ -43,7 +23,7 @@ BCP 14 и списки эквивалентных словесных форм IS
|
|||||||
Работа читательская, машине не даётся; в список проверок она уже записана в
|
Работа читательская, машине не даётся; в список проверок она уже записана в
|
||||||
разделе «Чтением, потому что машине не даётся».
|
разделе «Чтением, потому что машине не даётся».
|
||||||
|
|
||||||
## 3. Описание языка отдельно от набора конвенций
|
## 2. Описание языка отдельно от набора конвенций
|
||||||
|
|
||||||
`LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции;
|
`LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции;
|
||||||
`conventions/` — **один конкретный** набор. Сейчас они склеены в одном
|
`conventions/` — **один конкретный** набор. Сейчас они склеены в одном
|
||||||
@@ -68,7 +48,7 @@ BCP 14 и списки эквивалентных словесных форм IS
|
|||||||
|
|
||||||
# Канон, тулинг, подключение
|
# Канон, тулинг, подключение
|
||||||
|
|
||||||
## 4. Тулинг: две разные задачи в одном `conv`
|
## 3. Тулинг: две разные задачи в одном `conv`
|
||||||
|
|
||||||
Сейчас в `conv` смешаны две категории работы, и они расходятся по всему —
|
Сейчас в `conv` смешаны две категории работы, и они расходятся по всему —
|
||||||
по частоте запуска, по тому, кто запускает, и по тому, что считается
|
по частоте запуска, по тому, кто запускает, и по тому, что считается
|
||||||
@@ -109,7 +89,7 @@ BCP 14 и списки эквивалентных словесных форм IS
|
|||||||
манифеста и `vendir.yml` — как пример того, где проходит граница между «чего
|
манифеста и `vendir.yml` — как пример того, где проходит граница между «чего
|
||||||
хочу» и «что получил».
|
хочу» и «что получил».
|
||||||
|
|
||||||
## 5. Пары слоёв и темы без базы
|
## 4. Пары слоёв и темы без базы
|
||||||
|
|
||||||
Отложено сознательно, но список стоит держать перед глазами:
|
Отложено сознательно, но список стоит держать перед глазами:
|
||||||
|
|
||||||
@@ -130,7 +110,7 @@ BCP 14 и списки эквивалентных словесных форм IS
|
|||||||
- Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из
|
- Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из
|
||||||
`web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне.
|
`web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне.
|
||||||
|
|
||||||
## 6. Подключение к репозиториям
|
## 5. Подключение к репозиториям
|
||||||
|
|
||||||
Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server.
|
Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server.
|
||||||
Понадобится: заполнить локальную часть копий тем, что сейчас в этих
|
Понадобится: заполнить локальную часть копий тем, что сейчас в этих
|
||||||
@@ -139,7 +119,7 @@ BCP 14 и списки эквивалентных словесных форм IS
|
|||||||
строка в `AGENTS.md` каждого потребителя про то, что файлы в
|
строка в `AGENTS.md` каждого потребителя про то, что файлы в
|
||||||
`docs/conventions/` — копии.
|
`docs/conventions/` — копии.
|
||||||
|
|
||||||
## 7. Тулинг на Go, живущий независимо
|
## 6. Тулинг на Go, живущий независимо
|
||||||
|
|
||||||
Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в
|
Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в
|
||||||
одном репозитории и правятся одним движением. Мысль: вынести в отдельный
|
одном репозитории и правятся одним движением. Мысль: вынести в отдельный
|
||||||
@@ -148,10 +128,10 @@ Go-бинарь со своим релизным циклом, ставить ч
|
|||||||
|
|
||||||
Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править
|
Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править
|
||||||
инструмент «заодно» с правкой конвенции, работает против **любого** канона и
|
инструмент «заодно» с правкой конвенции, работает против **любого** канона и
|
||||||
любого потребителя — что прямо требуется вопросом 3, — и снимает питон из
|
любого потребителя — что прямо требуется вопросом 2, — и снимает питон из
|
||||||
зависимостей репозиториев-потребителей.
|
зависимостей репозиториев-потребителей.
|
||||||
|
|
||||||
Порядок обратный ожидаемому: пока вопрос 3 не сделан, инструмент всё равно
|
Порядок обратный ожидаемому: пока вопрос 2 не сделан, инструмент всё равно
|
||||||
работает против одного конкретного канона, и независимый релизный цикл ему
|
работает против одного конкретного канона, и независимый релизный цикл ему
|
||||||
нечего обслуживать. Сначала 3, потом 7. Разделение из вопроса 4 при этом
|
нечего обслуживать. Сначала 2, потом 6. Разделение из вопроса 3 при этом
|
||||||
дешевле заложить сразу, чем отпиливать потом.
|
дешевле заложить сразу, чем отпиливать потом.
|
||||||
|
|||||||
Reference in New Issue
Block a user