Restructure software catalog
This commit is contained in:
@@ -1,182 +1,84 @@
|
||||
# Каталог программ
|
||||
# Каталог программ Siemens
|
||||
|
||||
Репозиторий хранит дистрибутивы программ и их метаданные. Все пользовательские
|
||||
названия и описания пишутся на русском языке. Официальные названия программ,
|
||||
версии, имена платформ и другие технические значения переводить не нужно.
|
||||
Дистрибутивы хранятся в `catalog`, формат метаданных описан в
|
||||
`schema/index.schema.json`. Названия и описания — на русском языке.
|
||||
|
||||
## Структура
|
||||
|
||||
Корень репозитория одновременно является корнем каталога программ. Вложенность
|
||||
категорий не ограничена. Имя папки служит стабильным машиночитаемым
|
||||
идентификатором: используйте строчные латинские буквы, цифры, дефис и
|
||||
подчёркивание.
|
||||
|
||||
```text
|
||||
./
|
||||
catalog/
|
||||
├── index.yaml
|
||||
├── schema/
|
||||
│ └── index.schema.json
|
||||
└── system/
|
||||
└── category/
|
||||
├── index.yaml
|
||||
└── file-managers/
|
||||
└── program/
|
||||
├── index.yaml
|
||||
└── example-program/
|
||||
├── index.yaml
|
||||
├── img/
|
||||
│ └── screenshot.png
|
||||
└── files/
|
||||
├── example-program-1.0.0.zip
|
||||
├── example-program-1.1.0.zip
|
||||
└── manual.pdf
|
||||
├── files/
|
||||
└── img/
|
||||
```
|
||||
|
||||
Каждая категория и каждая программа содержит ровно один `index.yaml`:
|
||||
|
||||
- `type: category` означает категорию; рядом могут находиться подкатегории и
|
||||
программы;
|
||||
- `type: program` означает программу; все её версии описываются в этом же
|
||||
файле;
|
||||
- `img` и `files` — зарезервированные папки внутри программы.
|
||||
|
||||
Папки без `index.yaml`, например корневая `schema`, не входят в дерево
|
||||
категорий.
|
||||
|
||||
Список дочерних элементов категории не дублируется в YAML: он определяется по
|
||||
вложенным папкам. Благодаря этому перемещение программы не требует правки
|
||||
родительских индексов.
|
||||
Каждая категория и программа имеет один `index.yaml`. Дочерние элементы
|
||||
определяются по папкам и не перечисляются в YAML. Все версии программы находятся
|
||||
в одном индексном файле.
|
||||
|
||||
## Категория
|
||||
|
||||
```yaml
|
||||
format: 1
|
||||
type: category
|
||||
name: Системные программы
|
||||
description: Утилиты для настройки и обслуживания устройства.
|
||||
name: Название категории
|
||||
order: -10
|
||||
description: Описание категории.
|
||||
```
|
||||
|
||||
`order` необязателен; меньшее значение выводится раньше.
|
||||
|
||||
## Программа
|
||||
|
||||
```yaml
|
||||
format: 1
|
||||
type: program
|
||||
name: Пример программы
|
||||
name: Название программы
|
||||
summary: Короткое назначение программы для списка категории.
|
||||
description: |-
|
||||
Краткое описание назначения и возможностей программы.
|
||||
|
||||
Возможности:
|
||||
- первая возможность;
|
||||
- вторая возможность.
|
||||
homepage: https://example.org/program
|
||||
source: https://github.com/example/program
|
||||
Полное описание в Markdown.
|
||||
homepage: https://example.org
|
||||
source: https://github.com/example/project
|
||||
author: Автор
|
||||
screenshots:
|
||||
- img/screenshot.png
|
||||
versions:
|
||||
- version: "1.1.0"
|
||||
- version: "1.2.0"
|
||||
status: current
|
||||
released: "2007-08-14"
|
||||
files:
|
||||
- path: files/example-program-1.1.0.zip
|
||||
description: Дистрибутив программы
|
||||
- path: files/program-1.2.0.zip
|
||||
description: Дистрибутив
|
||||
platform: win32
|
||||
size: 123456
|
||||
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`
|
||||
необязательны.
|
||||
Обязательные поля программы: `format`, `type`, `name`, `summary`, `description`,
|
||||
`screenshots`, `versions`. Значения `platform`: `win32`, `win64`, `dos`, `java`,
|
||||
`j2me`. Значения `status`: `current`, `archived`.
|
||||
|
||||
Поле `description` содержит Markdown. Для содержательного описания используйте
|
||||
абзацы и списки внутри литерального YAML-блока `|-`.
|
||||
Файлы версий указываются в `versions[].files`, общие файлы — в
|
||||
`additional_files`. Пути файлов начинаются с `files/`, скриншотов — с `img/`.
|
||||
`size` содержит размер в байтах. Архивы хранятся через Git LFS.
|
||||
|
||||
Все файлы программы хранятся в её папке `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 fill-metadata
|
||||
pnpm fill-metadata:check
|
||||
pnpm tree
|
||||
pnpm typecheck
|
||||
```
|
||||
|
||||
Можно вывести только выбранную ветку, добавить пути каталогов или версии
|
||||
программ:
|
||||
|
||||
```shell
|
||||
pnpm tree service/repair-tools
|
||||
pnpm tree --paths
|
||||
pnpm tree --versions
|
||||
```
|
||||
|
||||
Формальная JSON Schema находится в
|
||||
[`schema/index.schema.json`](schema/index.schema.json). Она проверяет структуру
|
||||
и значения `index.yaml`; соответствие русского текста проверяется при ревью,
|
||||
поскольку название продукта может состоять из латинских символов.
|
||||
`fill-metadata` заполняет `size` и `sha256`. Команда принимает путь к программе,
|
||||
категории или `index.yaml`. `tree` принимает путь и флаги `--paths`,
|
||||
`--versions`.
|
||||
|
||||
Reference in New Issue
Block a user