162 lines
11 KiB
Markdown
162 lines
11 KiB
Markdown
# Правила ведения каталога
|
||
|
||
Эти правила действуют для всего репозитория. Перед изменением метаданных сверяйся
|
||
с `schema/index.schema.json`. Не добавляй поля, которых нет в схеме.
|
||
|
||
## Структура
|
||
|
||
- Все категории и программы находятся внутри корневой папки `catalog`.
|
||
`catalog/index.yaml` описывает корневую категорию.
|
||
- Каждая категория и каждая программа внутри `catalog` находятся в собственной
|
||
папке и содержат ровно один файл `index.yaml`.
|
||
- Вложенность категорий не ограничена. Дочерние категории и программы
|
||
определяются по файловой структуре и не перечисляются в индексе категории.
|
||
- Имя папки — стабильный идентификатор. Используй строчные латинские буквы,
|
||
цифры, дефис и подчёркивание.
|
||
- В папке программы все загружаемые файлы находятся в `files`, а скриншоты — в
|
||
`img`.
|
||
- Не создавай отдельные YAML-файлы или папки метаданных для версий. Все версии
|
||
описываются в `versions` единственного `index.yaml` программы.
|
||
- Папки без `index.yaml`, например `schema`, `files` и `img`, не являются
|
||
категориями.
|
||
|
||
## YAML категории
|
||
|
||
Используй только следующие обязательные поля и сохраняй их порядок:
|
||
|
||
```yaml
|
||
format: 1
|
||
type: category
|
||
name: Русское название категории
|
||
order: -10
|
||
description: Описание категории на русском языке.
|
||
```
|
||
|
||
`order` — необязательное целое число для сортировки соседних категорий. Меньшее
|
||
значение выводится раньше, отсутствие поля равнозначно `order: 0`. При равных
|
||
значениях категории сортируются по названию. Располагай `order` после `name`.
|
||
|
||
## YAML программы
|
||
|
||
Поля программы располагай в следующем порядке:
|
||
|
||
1. `format: 1` — обязательное поле.
|
||
2. `type: program` — обязательное поле.
|
||
3. `name` — обязательное официальное название программы.
|
||
4. `summary` — обязательное короткое описание программы на русском языке.
|
||
5. `description` — обязательное подробное описание на русском языке в формате
|
||
Markdown.
|
||
6. `homepage` — необязательный URL домашней страницы.
|
||
7. `source` — необязательный URL исходного кода.
|
||
8. `author` — необязательное имя автора или название организации-разработчика.
|
||
9. `screenshots` — обязательный массив путей; используй `[]`, если изображений
|
||
нет.
|
||
10. `versions` — обязательный непустой массив версий.
|
||
11. `additional_files` — необязательный массив файлов, не привязанных к версии.
|
||
|
||
Новые версии добавляй в начало `versions`, от новых к старым. Каждая версия
|
||
имеет такой вид:
|
||
|
||
```yaml
|
||
- version: "1.2.0"
|
||
status: current
|
||
released: "2007-08-14"
|
||
files:
|
||
- path: files/program-1.2.0.zip
|
||
description: Назначение файла на русском языке
|
||
platform: win32
|
||
size: 123456
|
||
sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
|
||
```
|
||
|
||
Поля версии располагай в порядке `version`, `status`, `released`, `description`,
|
||
`files`. Обязательны только `version` и непустой массив `files`. Необязательный
|
||
`status` принимает `current` для актуальной версии и `archived` для устаревшей,
|
||
сохранённой ради архива. Если статусы используются у программы, указывай их у
|
||
всех её версий. Поле `released` добавляй только при наличии достоверной даты.
|
||
Не переноси changelog в `description` версии и не добавляй это поле для полноты.
|
||
Оно допустимо только в особом случае, когда нужно зафиксировать существенное
|
||
ограничение, которое нельзя выразить номером версии или описанием конкретного
|
||
файла.
|
||
|
||
Необязательное поле файла `platform` принимает одно из значений: `win32`,
|
||
`win64`, `dos`, `java` или `j2me`. Для Windows разрядность входит в название
|
||
платформы; отдельное поле `architecture` не используется.
|
||
|
||
Поля файла располагай в порядке `path`, `description`, `platform`, `size`,
|
||
`sha256`. `size` содержит размер файла в байтах. Поля `size` и `sha256`
|
||
заполняются командой `pnpm fill-metadata` и вручную не редактируются.
|
||
|
||
### Короткое описание
|
||
|
||
`summary` выводится рядом с названием программы в списке категории. Напиши
|
||
естественное краткое описание, по которому понятно, что это за программа, для
|
||
чего она нужна и с какими телефонами или форматами работает. Опирайся на полное
|
||
описание и технический смысл программы, а не на единый шаблон. Не используй
|
||
оценочные усилители вроде «комплексная», «универсальная», «мощная» или
|
||
«полноценная».
|
||
|
||
Файлы, которые подходят ко всем версиям или существуют отдельно от релиза,
|
||
помещай в `additional_files`, а не внутрь случайной версии:
|
||
|
||
```yaml
|
||
additional_files:
|
||
- path: files/manual.pdf
|
||
description: Руководство пользователя
|
||
```
|
||
|
||
## Текст и достоверность
|
||
|
||
- Названия категорий, описания программ, версий и файлов пиши на русском языке.
|
||
Официальные названия продуктов и технологий не переводи.
|
||
- Сохраняй полноту исходного описания. Не сокращай перечень возможностей до
|
||
общего пересказа и не удаляй значимые технические подробности.
|
||
- Содержимое каждого `description` интерпретируется как Markdown. Для длинного
|
||
описания со списком используй литеральный блок `|-` и Markdown-списки; для
|
||
обычного абзаца, перенесённого на несколько строк, используй `>-`. Не вставляй
|
||
HTML-разметку.
|
||
- Не выдумывай даты, ссылки, возможности или платформы. Неизвестное
|
||
необязательное поле лучше не добавлять.
|
||
- Сначала пытайся определить версию по странице, имени файла, README и
|
||
метаданным бинарника. Если номер версии нигде не указан и достоверно получить
|
||
его невозможно, используй каталоговое значение `version: "1.0"`. Не выводи
|
||
номер версии из даты сборки.
|
||
- Если источник содержит только текущую версию, добавляй только её. Не ищи
|
||
более ранние архивы в Wayback Machine без отдельного указания пользователя.
|
||
|
||
## Пути и файлы
|
||
|
||
- Все пути относительны папке программы и используют `/`.
|
||
- Путь загружаемого файла начинается с `files/`; путь скриншота — с `img/`.
|
||
- Абсолютные пути, `..` и обратная косая черта запрещены.
|
||
- Каждый путь из YAML должен указывать на существующий файл.
|
||
- Один файл нельзя одновременно указывать в `versions` и `additional_files`.
|
||
- Для каждого добавленного файла указывай размер в байтах и SHA-256 в нижнем
|
||
регистре.
|
||
- Архивы должны проходить через Git LFS согласно `.gitattributes`. Остальные
|
||
файлы хранятся в обычном Git.
|
||
|
||
## Стиль YAML
|
||
|
||
- Кодировка — UTF-8, окончания строк — LF, отступ — два пробела, табуляция
|
||
запрещена.
|
||
- Версии и даты всегда заключай в двойные кавычки.
|
||
- Дата имеет формат `YYYY-MM-DD`, SHA-256 — ровно 64 шестнадцатеричных символа.
|
||
- Не используй YAML-теги, anchors, aliases и merge keys.
|
||
- Не допускай неизвестных полей и дубликатов в массивах.
|
||
|
||
## Проверка
|
||
|
||
Перед завершением изменения:
|
||
|
||
1. Проверь синтаксис всех затронутых `index.yaml` безопасным YAML-парсером.
|
||
2. Проверь их по `schema/index.schema.json` валидатором JSON Schema Draft 2020-12,
|
||
если он доступен.
|
||
3. Убедись, что все пути существуют, а их размеры и SHA-256 совпадают с
|
||
метаданными. Для заполнения и обновления используй
|
||
`pnpm fill-metadata [путь]`, для проверки без изменения файлов —
|
||
`pnpm fill-metadata:check [путь]`.
|
||
4. Для каждого нового архива выполни `git check-attr filter -- <путь>` и
|
||
убедись, что значение равно `lfs`.
|
||
5. Выполни `git diff --check`.
|