Формат карточек

Карточки с краткой информацией и важными ссылками о программном обеспечении. Отображаются на страницах подборок и программ.

Определение

• Директория: /data/cards/
• Формат: YAML

Название файла — идентификатор. Разрешены только строчные латинские буквы, цифры и дефис. Пример: файл example.yaml задаёт карточку с идентификатором example. Эта карточка может использоваться для страницы /software/example и/или подборок при написании {{ < card example >}}.

Одна карточка должна определять одно значимое программное обеспечение: приложение, сервис, расширение. Есть случаи, когда под одним и тем же или похожим названием распространяются разные варианты программного обеспечения. Например, приложение для компьютера и телефона имеют различную функциональность, кодовую базу, формат сопровождения. Тогда поля должны быть заполнены, считая первоначально выпущенный / главный вариант ПО основным источником данных.

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

Поля

Смотрите файл !TEMPLATE, чтобы узнать эталонное расположение полей. В других файлах этой директории можно узнать реальные примеры использования.

Общие правила:

• Ссылки всегда должны указывать на страницу со значимой информацией. Читатели должны переходить по ссылкам, чтобы узнавать полезную информацию, а не видеть заглушки и недоработанные тексты.

• Необязательные поля можно убрать, если их нельзя однозначно заполнить.

• При заполнении многострочных полей используйте знак > в YAML.

title

Строка, обязательно — Название программного обеспечения.

Стилистика написания (заглавные буквы, разделение слов, знаки препинания) должна строго соответствовать оригинальному названию.

icon

Строка (название файла), необязательно — Значок (логотип) программного обеспечения.

Значки хранятся в директории /content/assets/logos/. Предпочтителен формат SVG. Обычно можно найти в репозитории, на официальном сайте (assets / press kit) или на Wikimedia Commons. При необходимости можно изменить размер или соотношение сторон, но не отдельные элементы (цвета, формы). При сохранении SVG в Inkscape нужно выбирать формат «Оптимизированный SVG» (Optimized SVG).

Если название файла совпадает с идентификатором карточки и в формате SVG, то это поле не нужно. Иначе заполнить название файла.

description

Строка, обязательно — Краткое описание программного обеспечения.

Должно лаконично в один абзац рассказать основную суть. Нет определённого ограничения на количество слов/знаков. Старайтесь не включать излишнюю подробную информацию, которая могла бы быть описана на странице. В первую очередь должно быть рассказано о наиболее важных характеристиках. Не используйте бессмысленные маркетинговые выражения.

Описание отображается под заголовком и в предпросмотре ссылок отдельных страниц. Оно копируется в буфер обмена при нажатии на кнопку “Поделиться”.

alert

Объект, необязательно — Цветной информативный блок.

Отображается под описанием и служит для предоставления информации, требующей особого внимания (например, отсутствие обновлений продолжительный период). Это то же самое, что и цветные блоки цитат на страницах.

Доступные варианты: note (примечание - синий), tip (совет - зелёный), important (важно - фиолетовый), warning (внимание - оранжевый), caution (осторожно - красный).

alert:
  type: warning
  content: >
    **Содержимое цветного блока** с поддержкой [Markdown](https://example.com)

homepage

Строка (ссылка), обязательно — Официальный сайт (домашняя страница).

Должен быть отдельный сайт на собственном домене (https://example.com) или поддомене (https://project.example.com), принадлежащий владельцам программного обеспечения или доверенным лицам. В некоторых случаях это может быть отдельная страница (https://example.com/project).

Если нет официального сайта, то обычно вместо него выступает репозиторий с исходным кодом. Тогда можно использовать ссылку на него с указателем на файл README (https://git.example.com/org/repo#readme).

Если официальный сайт является документацией для пользователя, то это поле можно не заполнять.

Если есть домен, который только перенаправляет на репозиторий, то нужно использовать домен в качестве ссылки. Возможно, в будущем на домене появится полноценный сайт.

userDocs

Строка (ссылка), необязательно — Официальная документация для пользователей (руководство пользователя, справка, вики, часто задаваемые вопросы).

Страницы на сайте Kool Tech Tricks часто содержат полезную информацию о программном обеспечении и его использовании. Страницы должны помогать пользователям изучать программы и разбираться в их использовании, поскольку часто нужная информация не лежит на поверхности или предоставлена плохо. Но страницы на сайте Kool Tech Tricks не должны заменять официальную документацию. Официальная документация почти всегда содержит более точную, подробную и актуальную информацию, на которую пользователи должны опираться в первую очередь. Поэтому ссылка на документацию выделена на первый план.

Поле userDocs должно содержать ссылку на официальную документацию для пользователей. Ссылка должна указывать на конкретный раздел документации только если остальные не содержат полезной информации для пользователей.

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

extras

Раскрывающийся блок с дополнительными ссылками и информацией, которая не требуется для представления на первом плане.

owner

Строка (Markdown), обязательно — Владелец программного обеспечения (компания, организация, сообщество, отдельные разработчики).

Владелец принимает важные решения по развитию программного обеспечения и активно участвует в разработке. Это напрямую влияет на функциональность программного обеспечения. Например, приложения от коммерческой компании часто создаются с целью извлечения выгоды из пользователей, поэтому содержат рекламу и навязчивые функции. Приложения от независимых некоммерческих организаций и групп разработчиков в свою очередь сосредоточены на предоставлении удобного пользовательского опыта. С другой стороны, сообщество энтузиастов может быть недостаточно ответственным и профессиональным, в отличие от нанятых опытных разработчиков в компаниях.

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

Если над программным обеспечением работает группа независимых разработчиков, и нельзя однозначно сказать “кто главный”, то следует указать в качестве владельца “Сообщество энтузиастов”.

initialRelease

Строка (дата), обязательно — Дата первоначального публичного релиза.

Это дата, когда программное обеспечение впервые становится возможным загрузить и начать использовать любому желающему. Считаются ранние выпуски до 1.0 (альфа, бета) и версии до ребрендинга.

Не является публичным релизом:

• Отсутствие готовых сборок для скачивания, если в будущем планируется их предоставлять.
• Запись в список ожидания.
• Доступ для ограниченного количества пользователей.
• Требование подписки для ранней версии, если в будущем планируется бесплатный релиз.

Дата указывается в формате ГГГГ-ММ-ДД. Если неизвестна точная дата, можно указать в формате ГГГГ-ММ или ГГГГ, а также любую строку.

Найти точную дату первого релиза может быть трудно. Дата на Википедии может помочь, но она не всегда указана корректно.

news

Строка (ссылка), необязательно — Новости проекта (блог, пресс-релизы).

Не путать со списком изменений. Новости предназначены для сообщения конкретных крупных обновлений, планов развития, рассказы из жизни проекта.

changelog

Строка (ссылка), необязательно — Список изменений (заметки об обновлениях).

Содержит сводку о наиболее заметных изменениях в новых версиях программного обеспечения. Предпочтительно, чтобы это была отдельная страница на сайте или файл (CHANGELOG.md).

Можно указывать несколько списков изменений:

changelog:
  - title: Android
    url: https://example.com/android/CHANGELOG.md
  - title: iOS
    url: https://example.com/ios/CHANGELOG.md

issues

Строка (ссылка), необязательно — Отчёты об ошибках и предложениях (баг-трекер).

Страница, на которой читатель может ознакомиться со списком известных проблем, сообщить об ошибке или предложить изменение.

donate

Строка (ссылка), необязательно — Поддержать разработчиков (пожертвования).

Страница, где читатель может (материально) поддержать разработчиков программного обеспечения.

community

Блок ссылок на официальные сообщества программного обеспечения — чаты и социальные сети. Их должны вести либо представители проекта, либо доверенные участники сообщества. Необходимо брать ссылки из официальных ресурсов, а не искать вручную на сайтах платформ. Не указывайте ссылки на личные аккаунты/профили разработчиков.

Все поля являются либо ссылками, либо именами пользователей на соответствующих платформах.

rules

Ссылка на страницу с правилами поведения сообщества (Code of Conduct). Она отображается в примечании над всеми ссылками, чтобы напомнить о необходимости соблюдать порядок.

forum

Ссылка на форум. Это может быть как отдельный сайт, основанный на соответствующей платформе (например, Discourse), так и обсуждения в рамках репозитория (GitHub Discussions).

bluesky

Имя пользователя в Bluesky. Является доменом, который обычно совпадает с официальным сайтом. Например, bsky.app — имя пользователя, что формирует ссылку https://bsky.app/profile/bsky.app.

discord

Ссылка-приглашение в Discord (https://discord.gg/...). Часто такие ссылки случайно сгенерированные и непостоянные. Поэтому, если возможно, следует указывать ссылку переадресации.

lemmy

Ссылка на сообщество в Lemmy или аналогичные платформы, совместимые с Fediverse (Piefed) — https://lemmy.example.com/c/community. Это альтернатива Reddit.

mastodon

Ссылка на аккаунт в Mastodon или аналогичные платформы для микроблога, совместимые с Fediverse (Misskey, GoToSocial) — https://instance.example.com/@username.

Иногда в имени пользователя содержится основной домен, а сервер размещён на поддомене. В таком случае нужно в конце добавить домен имени пользователя: https://instance.example.com/@username@example.com.

matrix

Идентификатор комнаты или пространства в Matrix: room:example.com. Будет сформирована ссылка https://go.kde.org/matrix/#/#room:example.com, которая отобразит предпросмотр комнаты в браузере и предложит открыть чат в мессенджере.

reddit

Название сообщества (сабреддита) в Reddit: example. Будет преобразовано в https://old.reddit.com/r/example.

telegram

Имя пользователя в Telegram: username. Будет преобразовано в https://t.me/username. Канал приоритетнее, так как он обычно содержит ссылку на чат.

xitter

Имя пользователя в X (ранее и до сих пор известный как Twitter): twitter. Будет преобразовано в https://x.com/twitter.

technicalInfo

Блок с технической информацией, которую необязательно знать каждому читателю.

license

Строка (ссылка) или список объектов, обязательно — Лицензия(-и), по которой(-ым) распространяется программное обеспечение.

Свободное ПО с открытым исходным кодом распространяется по лицензиям, определённым в директории /data/licenses/. Вы можете использовать идентификаторы этих лицензий.

Проприетарное ПО с закрытым исходным кодом должно использовать лицензию proprietary.

Можно указать несколько лицензий или нестандартные:

license:
  - id: gnu-agpl-3.0-or-later
  - id: mit
    note: Примечание, если эта лицензия применяется только к определённой части ПО
  - title: Нестандартная лицензия
    url: https://example.com/license.txt

repository

Строка (ссылка), необязательно — Репозиторий(-и) с исходным кодом.

Если доступно несколько репозиториев под одной организацией, то следует указывать ссылку на организацию.

Если ПО проприетарное, то исходный код всё равно может быть частично доступен.

techDocs

Строка (ссылка), необязательно — Техническая документация.

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

tech

Строка (Markdown), необязательно — Используемые технологии.

Пример:

• Фреймворки: Electron, Tauri, Qt, GTK, Flutter, React Native.
• Библиотеки: .NET, SwiftUI, Jetpack Compose, React, Svelte.
• Основа: Firefox (Gecko), Chromium (Blink).
• Форки: продолжение, ответвление.

Не предпочтительно указывать языки программирования, если в этом нет необходимости.

llmAssistance

Строка (Markdown), необязательно — Применение AI/LLM при разработке.

Генеративный ИИ создаёт множество проблем и рисков. Он часто генерирует низкокачественное содержимое в большом объёме, которое может быть трудно поддерживать. С другой стороны, языковые модели могут эффективно находить уязвимости и справляться с монотонной работой. Тем не менее некоторые пользователи обеспокоены, что написание кода с помощью ИИ сделает программу менее надёжной.

Поле llmAssistance информирует читателей о том, что в данном ПО при разработке применяют AI/LLM, но данная информация всё равно должна восприниматься с долей скептицизма. При оценке степени применения ИИ может возникнуть множество вопросов, так как эта тема достаточно обширна, чтобы строго описать её в одном поле. Не всегда возможно с точностью определить, что результат работы был сгенерирован. Поэтому это поле заполняется в свободной форме, и предпочтительно оставлять ссылки.

Какие случаи рассматриваются:

• Генерация кода: Когда разработчики просят языковую модель реализовать какую-либо функциональность в программе или переписать существующую. Обычно в таком случае в репозитории числятся “контрибьюторы” Claude и Cursor. Разработчики могут проверять весь код и понимать что он делает. Но есть риск, что в долгосрочной перспективе кодовую базу всё равно станет трудно поддерживать без применения ИИ.

• Генерация ресурсов: Изображения, аудио, видео, текст, а также в некоторых случаях сайт и интерфейс. Разработчики программного обеспечения обычно недостаточно талантливы, чтобы создавать оригинальные качественные ресурсы. С другой стороны, это может быть простое нежелание и стремление поскорее закончить проект. Сгенерированные ресурсы обычно служат маркером, что разработчики недостаточно заботливо относятся к своему проекту, и могут быть дружелюбны к применению ИИ.

• Политика использования ИИ: Документ для контрибьюторов (CONTRIBUTING.md) или инструкции для агентов (CLAUDE.md, AGENTS.md). Он может разрешать применение ИИ при разработке, что приводит к сгенерированному коду как со стороны разработчиков, так и со стороны контрибьюторов. Так как сгенерированный код от контрибьюторов часто является слоп-спамом, некоторые разработчики ограничивают применение ИИ, заставляя более ответственно относится к отправляемому коду. Также может быть запрещено генерировать какой-либо код.

Не рассматривается:

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

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

• ИИ-функциональность: Это не технические сведения, об этом следует написать в содержимом страницы или в описании.

Можно использовать ресурс open-slopware в качестве справки.

externalLinks

Ссылки на внешние ресурсы, не связанные ни с данным программным обеспечением, ни с Kool Tech Tricks, но всё равно могут быть полезны для ознакомления.

Если эти сайты содержат отдельную страницу про данное ПО, то можно оставить ссылку в этом разделе.

wikipedia

Википедия — свободная энциклопедия, которую может редактировать каждый.

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

archWiki

ArchWiki — вики-ресурс, посвящённый Arch Linux.

Часто информация на ArchWiki оказывается полезна пользователям других дистрибутивов Linux.

fourPda

4PDA — крупнейший русскоязычный форум, посвящённый обсуждению мобильных устройств, программного обеспечения и цифровых технологий.

Для многих Android-приложений существуют отдельные ветки обсуждений, на которые можно оставить ссылку.

isItReallyFoss

Is it really FOSS? — сайт, который рассказывает о том, насколько ПО с открытым исходным кодом является свободным.

Нередко программное обеспечение, рекламирующееся как “с открытым исходным кодом” на самом деле имеет скрытые ограничения.

get

Ссылки на загрузки. Может быть убрано, если речь идёт об онлайн-сервисе.

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

• Android: Необходимо указать как минимум один способ установки вне Google Play. Google Play должен быть первым способом установки. Если APK-файл (с сайта или Git-системы) имеет автообновления, то ссылка на него указывается следующей. Иначе это последняя ссылка, а следующей вместо неё идёт Obtainium со схемой obtainium:// (иногда можно взять у разработчиков, на сайте готовых конфигураций или составить из obtainium://add/ссылка). Затем идут ссылки на сторонний репозиторий F-Droid, IzzyOnDroid и официальный F-Droid.

title

Строка, необязательно — Заголовок раздела.

По умолчанию “Скачать”, но в случае веб-приложений может быть “Открыть”, операционных систем — “Установить”.

linkButtons

Ссылки в виде кнопок.

- group: Группа
- title: Ссылка
  icon: icon # значок
  url: https://example.com/download

group

Ссылки могут быть группированы, и это поле служит в качестве разделителя. Когда программа доступна для нескольких платформ, у которых доступно несколько вариантов скачивания, рекомендуется выделить их в отдельные группы.

title

Название ссылки, которое отображается на кнопке.

Предпочтительно указывать название способа установки (Google Play, App Store, Microsoft Store), а в скобках — платформу (Android, iOS, Windows), если платформа не задана группой.

Если это единственный способ установки для данной платформы, который находится в одной группе ссылок, то можно указать только название платформы.

icon

Значок ссылки. Должен соответствовать заголовку.

• Material Icons: web (веб, браузер, официальный сайт), experiment, (экспериментальная версия), computer, developer-guide (инструкция), package-2 (пакеты), sports-bar (Homebrew).
• Источники: accrescent, app-store, codeberg, f-droid, flathub, google-play, github, gitlab, izzyondroid, obtainium.
• Платформы: android, apple, chromium, firefox, linux, safari, windows.

url

Ссылка на установку.

Если это Obtainium, то используйте схему obtainium:// для мгновенного открытия в приложении. Аналогично со сторонними репозиториями F-Droid: fdroidrepos://.

linkList

Ссылки в виде списка. Подойдёт в случаях, когда нужно описать сложные варианты установки. Порядок задаётся числовым префиксом. Может быть несколько уровней вложенности.

1 Windows:
  1 Официальный сайт: https://example.com
  2 GitHub: https://github.com
2 Linux:
  1 Flathub: https://flathub.org
  2 GitHub: https://github.com
  3 Arch Linux: '`sudo pacman -S example`'
3 macOS:
  GitHub: https://github.com
4 Android:
  1 Google Play: https://play.google.com
  2 F-Droid: https://f-droid.org
  3 GitHub: https://github.com
5 iOS:
  AppStore: https://apple.com
6 Браузер: https://example.net
7 Chromium: https://chromewebstore.google.com
8 Firefox: https://addons.mozilla.org

note

Примечание. Отображается ниже всех ссылок.

screenshots

Скриншоты.

Изображения хранятся в директории /assets/screenshots/, в папке ПО (название совпадает с идентификатором). Предпочтительно формат WebP без потери качества, размер не больше 500 КБ.

screenshots:
  1 example: Описание изображения
  2 example-@: Описание изображения (@ = светлая + тёмная тема)
  3 example.png: Изображение с другим разрешением (не .webp)
  4 example-@.jpg: Комбинировано

• Порядок задаётся числовым префиксом. Он не является частью названия файла и обрезается при сборке сайте.
• Если изображение не .webp, название должно оканчиваться расширением.
• Светлая и тёмная тема задаётся в названии файла припиской light и dark соответственно. Знак @ в YAML-файле используется для сокращения задания скриншотов со светлой и тёмной темой.
• Каждый скриншот должен сопровождаться описанием.