Репозиторий хранит дистрибутивы программ и их метаданные. Все пользовательские названия и описания пишутся на русском языке. Официальные названия программ, версии, имена платформ и другие технические значения переводить не нужно.

Структура

Корень репозитория одновременно является корнем каталога программ. Вложенность категорий не ограничена. Имя папки служит стабильным машиночитаемым идентификатором: используйте строчные латинские буквы, цифры, дефис и подчёркивание.

./
├── 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: он определяется по вложенным папкам. Благодаря этому перемещение программы не требует правки родительских индексов.

Категория

format: 1
type: category
name: Системные программы
description: Утилиты для настройки и обслуживания устройства.

Программа

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:

pnpm install

Команда вычисляет контрольные суммы всех файлов из versions и additional_files, после чего добавляет или обновляет поля sha256:

pnpm sha256

Можно ограничить обход одной программой, категорией или конкретным индексом:

pnpm sha256 service/repair-tools/joker
pnpm sha256 service/repair-tools/joker/index.yaml

Для проверки без изменения YAML используется отдельная команда:

pnpm sha256:check

Дерево каталога

Дерево категорий и программ строится по файловой структуре и названиям из index.yaml:

pnpm tree

Можно вывести только выбранную ветку, добавить пути каталогов или версии программ:

pnpm tree service/repair-tools
pnpm tree --paths
pnpm tree --versions

Формальная JSON Schema находится в schema/index.schema.json. Она проверяет структуру и значения index.yaml; соответствие русского текста проверяется при ревью, поскольку название продукта может состоять из латинских символов.