Add Siemens software catalog

2026-08-17 22:07:35 +03:00
parent 6597f56e48
commit 2cc7a4c0d4
121 changed files with 2670 additions and 0 deletions
@@ -0,0 +1,182 @@
+# Каталог программ
+
+Репозиторий хранит дистрибутивы программ и их метаданные. Все пользовательские
+названия и описания пишутся на русском языке. Официальные названия программ,
+версии, имена платформ и другие технические значения переводить не нужно.
+
+## Структура
+
+Корень репозитория одновременно является корнем каталога программ. Вложенность
+категорий не ограничена. Имя папки служит стабильным машиночитаемым
+идентификатором: используйте строчные латинские буквы, цифры, дефис и
+подчёркивание.
+
+```text
+./
+├── index.yaml
+├── schema/
+│   └── index.schema.json
+└── system/
+    ├── index.yaml
+    └── file-managers/
+        ├── index.yaml
+        └── example-program/
+            ├── index.yaml
+            ├── img/
+            │   └── screenshot.png
+            └── files/
+                ├── example-program-1.0.0.zip
+                ├── example-program-1.1.0.zip
+                └── manual.pdf
+```
+
+Каждая категория и каждая программа содержит ровно один `index.yaml`:
+
+- `type: category` означает категорию; рядом могут находиться подкатегории и
+  программы;
+- `type: program` означает программу; все её версии описываются в этом же
+  файле;
+- `img` и `files` — зарезервированные папки внутри программы.
+
+Папки без `index.yaml`, например корневая `schema`, не входят в дерево
+категорий.
+
+Список дочерних элементов категории не дублируется в YAML: он определяется по
+вложенным папкам. Благодаря этому перемещение программы не требует правки
+родительских индексов.
+
+## Категория
+
+```yaml
+format: 1
+type: category
+name: Системные программы
+description: Утилиты для настройки и обслуживания устройства.
+```
+
+## Программа
+
+```yaml
+format: 1
+type: program
+name: Пример программы
+description: |-
+  Краткое описание назначения и возможностей программы.
+
+  Возможности:
+  - первая возможность;
+  - вторая возможность.
+homepage: https://example.org/program
+source: https://github.com/example/program
+screenshots:
+  - img/screenshot.png
+versions:
+  - version: "1.1.0"
+    status: current
+    released: "2007-08-14"
+    files:
+      - path: files/example-program-1.1.0.zip
+        description: Дистрибутив программы
+        platform: win32
+        sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+  - version: "1.0.0"
+    files:
+      - path: files/example-program-1.0.0.zip
+additional_files:
+  - path: files/manual.pdf
+    description: Руководство пользователя
+```
+
+Обязательные поля программы: `format`, `type`, `name`, `description`,
+`screenshots`, `versions`. Поля `homepage`, `source` и `additional_files`
+необязательны.
+
+Поле `description` содержит Markdown. Для содержательного описания используйте
+абзацы и списки внутри литерального YAML-блока `|-`.
+
+Все файлы программы хранятся в её папке `files`. Версионные файлы перечислены
+в `versions[].files`, а не зависящие от версии — в `additional_files`. Один и
+тот же файл не следует указывать в обоих местах. Новые версии добавляются в
+начало массива `versions`, от новых к старым.
+
+Необязательное поле файла `platform` использует короткие машиночитаемые
+значения: `win32`, `win64`, `dos`, `java` или `j2me`. Отдельного поля
+архитектуры нет: разрядность Windows уже включена в `win32` или `win64`.
+
+Необязательное поле `status` принимает значение `current` для актуальной версии
+или `archived` для версии, оставленной в каталоге как архивная. Если программа
+использует статусы, они указываются у всех её версий.
+
+`description` версии используется только для существенных исключений, которые
+нельзя выразить номером версии или описанием файла. Обычный список изменений в
+индекс не переносится.
+
+Скриншоты хранятся в `img`; пути всегда начинаются с `img/`. Если скриншотов
+нет, указывается пустой массив: `screenshots: []`.
+
+## Правила формата
+
+- Кодировка всех YAML-файлов — UTF-8, окончания строк — LF.
+- `format` — версия формата метаданных. Текущее значение: `1`.
+- Неизвестные поля запрещены: расширение формата требует изменения схемы.
+- Все пути задаются относительно папки программы. Абсолютные пути, `..` и
+  обратная косая черта запрещены.
+- Даты записываются строкой `YYYY-MM-DD` и берутся в кавычки.
+- URL используют только `http` или `https`.
+- `sha256`, если указан, содержит 64 шестнадцатеричных символа в нижнем
+  регистре.
+- Массивы не должны содержать дубликаты.
+- Описания программы, версии и файла пишутся на русском языке.
+
+Архивы хранятся через Git LFS, остальные файлы — как обычные объекты Git.
+
+## Заполнение SHA-256
+
+Для установки зависимостей используется pnpm:
+
+```shell
+pnpm install
+```
+
+Команда вычисляет контрольные суммы всех файлов из `versions` и
+`additional_files`, после чего добавляет или обновляет поля `sha256`:
+
+```shell
+pnpm sha256
+```
+
+Можно ограничить обход одной программой, категорией или конкретным индексом:
+
+```shell
+pnpm sha256 service/repair-tools/joker
+pnpm sha256 service/repair-tools/joker/index.yaml
+```
+
+Для проверки без изменения YAML используется отдельная команда:
+
+```shell
+pnpm sha256:check
+```
+
+## Дерево каталога
+
+Дерево категорий и программ строится по файловой структуре и названиям из
+`index.yaml`:
+
+```shell
+pnpm tree
+```
+
+Можно вывести только выбранную ветку, добавить пути каталогов или версии
+программ:
+
+```shell
+pnpm tree service/repair-tools
+pnpm tree --paths
+pnpm tree --versions
+```
+
+Формальная JSON Schema находится в
+[`schema/index.schema.json`](schema/index.schema.json). Она проверяет структуру
+и значения `index.yaml`; соответствие русского текста проверяется при ревью,
+поскольку название продукта может состоять из латинских символов.