183 lines
8.2 KiB
Markdown
183 lines
8.2 KiB
Markdown
# Каталог программ
|
|
|
|
Репозиторий хранит дистрибутивы программ и их метаданные. Все пользовательские
|
|
названия и описания пишутся на русском языке. Официальные названия программ,
|
|
версии, имена платформ и другие технические значения переводить не нужно.
|
|
|
|
## Структура
|
|
|
|
Корень репозитория одновременно является корнем каталога программ. Вложенность
|
|
категорий не ограничена. Имя папки служит стабильным машиночитаемым
|
|
идентификатором: используйте строчные латинские буквы, цифры, дефис и
|
|
подчёркивание.
|
|
|
|
```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`; соответствие русского текста проверяется при ревью,
|
|
поскольку название продукта может состоять из латинских символов.
|