Філіп Візналл
philip@tecnocode.co.uk
Вілл Томпсон
wjt@endlessos.org
Мілан Чрха
mcrha@redhat.com
Як у Програмах використано метадані
Юрій Чорноіван
yurchor@ukr.net 2024

# Метадані програм

# Скріншоти

Програми показують знімки вікна програми на сторінці з подробицями щодо неї. Зазвичай це знімки всіляких вікон програми, щоб можна було швидко дізнатись про можливості програми, її вигляд тощо.

Коли у файлі метаданих декілька знімків вікно, їх буде показано у Програмах у форматі «каруселі».

У випадку, якщо файл метаданих не містить жодного знімка, буде показано піктограму-замінник, як нижче, з написом `Немає знімків`:

Піктограма-замінник може виглядати інакше, якщо ви користуєтеся нетиповою темою піктограм.

З розвитком інтерфейсу програми знімки вікон можуть застарівати. Тому, навіть якщо Програми показують знімки вікон певної програми, важливо перевірити, чи є ці знімки актуальними.

Ви можете удосконалити дані щодо знімка вікна програми:

Як додати знімки вікон

# Панель контексту програм

Панель контексту програм у Програмах є набором плиток на сторінці подробиць програми, де буде показано вказані нижче дані.

Сховище даних

Безпека

Підтримка апаратної частини

Віковий рейтинг

Ось панель контексту програм для програми Програми:

Плитки буде показано у вказаному вище порядку (починаючи з плитки `Сховище даних` ліворуч).

Докладні відомості щодо кожної плитки наведено нижче.

# Сховище даних

Програми показують плитку сховища даних на сторінці подробиць щодо програми. Якщо програму не встановлено, тут буде показано оцінку потрібного розміру отриманих даних для встановлення програми. Якщо програму встановлено, тут буде показано місце на диску, яке займають файли програми.

Розміри буде обчислено на основі даних, які надано модулем обробки Програм (зокрема flatpak або RPM), а не на основі даних, які вказано у метаданих програми. Редагування файла метаданих програми нічого не змінить на цій плитці. Тут його включено для повноти.

# Безпека

Програми показують плитку безпеки на сторінці подробиць щодо програми. Тут буде наведено резюме щодо того, слід вважати програму безпечною для встановлення і запуску, чи слід мати певні перестороги щодо довіри цій програмі.

На цій плитці поєднано відомості щодо прав доступу, яких програма потребуватиме для роботи (зокрема прав доступу до читання ваших файлів) із відомостями щодо способу розробки програми. Вільне програмне забезпечення, початковий код якого доступний до читання будь-кому, може бути безпечнішим за закрите, оскільки початковий код таких програм є придатним до вивчення.

У вікні, яке буде відкрито у відповідь на натискання плитки, буде показано списки різних прав доступу, які потрібні для роботи програми, а також деякі відомості щодо ліцензування та середовища виконання.

Ви можете удосконалити дані щодо захисту:

Як виправити неправильні відомості щодо захисту та прав доступу

# Підтримка апаратної частини

Програми покажуть плитку підтримки обладнання на сторінці з відомостями щодо програми. Тут буде поєднано відомості щодо вимог до апаратного забезпечення програми та апаратних можливостей комп'ютера з метою акцентування несумісностей чи невідповідностей вимогам — або щоб вказати, що програма має працювати правильно без несумісностей.

Програмний код спрямовано на пошук вказаного нижче обладнання. Перелік може бути розширено у майбутньому.

Чи наявна або потрібна підтримка сенсорної панелі, миші або клавіатури

Чи потрібен ігровий пульт

Мінімальний та рекомендований розмір дисплея, до якого може бути масштабовано вікно програми

Надійних способів визначити, чи використано ігровий пульт, оскільки часто пульти лишаються від'єднаними від комп'ютера, оскільки вони не потрібні для звичайного користування комп'ютером.

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

Ви можете удосконалити відомості щодо обладнання:

Як додати пропущені відомості щодо обладнання

# Віковий рейтинг

Програми показують плитку вікових обмежень на сторінці подробиць щодо програми. Тут буде показано віковий діапазон користувачів, для яких призначено програму, на основі даних щодо вмісту програми, які надаються самою програмою. Резюме цих даних буде наведено у форматі, подібному до вікових обмежень ігор або фільмів у вашій країні.

Наприклад, буде акцентовано, містить гра насильство або чи показує програма рекламу у своєму вікні.

У вікні, яке буде показано у відповідь на натискання плитки, буде показано списки різних типів вмісту програми та дані щодо того, наскільки критичним є вплив вмісту на користувача.

Ви можете удосконалити дані щодо вікових обмежень:

Як додати пропущені дані щодо вікових обмежень

# Ліцензування

Програми показують плитку, що вказує на те, чи є програма вільним програмним забезпеченням, чи її ліцензування є пропрієтарним, особливим або невідомим. На цій плитці буде показано докладніші відомості щодо ліцензування проєкту. Також на цій плитці буде показано список певних переваг вільного програмного забезпечення. Дізнатися більше

Іноді дані щодо ліцензування програми є неправильними, і програми, які насправді є вільним програмним забезпеченням, буде показано як «пропрієтарні». Так само, іноді дані щодо ліцензування є невідомими.

Програми підсвічують програми із вільним ліцензуванням і з відкритим кодом зеленим кольором, програми із пропрієтарним та особливим ліцензуванням — жовтим кольором, як це показано тут, Програми із невідомим ліцензуванням буде позначено сірим кольором.

Ви можете додати або удосконалити дані щодо ліцензування:

Як виправити неправильні відомості щодо ліцензування

# Посилання

Програми показують список посилань на ресурси програми на плитці посилань. Буде показано такі посилання:

| Посилання на сайт
| Посилання на сторінку пожертв
| Посилання на сторінку надсилання перекладів
| Посилання на сторінку звітування про вади
| Посилання на довідку
| Посилання на контактні дані

Буде показано деякі або усі ці посилання, залежно від того, чи вказано їх у файлі metainfo програми.

У випадку, якщо файл метаданих не містить жодного посилання, буде показано показану нижче плитку зі знаком питання.

Ви можете удосконалити посилання:

Як додати пропущені посилання

# Плитка-карусель

Програми, які рекомендують автори Програм буде показано у форматі каруселі у верхній частині головного вікна, як це показано тут. У кожної плитки каруселі колір тла визначається автоматично на основі видобутих з піктограми програми кольорів. Іноді цей колір тла є не зовсім правильним для програми, і його має бути явним чином розробником програми.

Набір рекомендованих програм визначається супровідниками дистрибутива Linux.

Ви можете удосконалити плитку-карусель:

Як встановити колір тла плитки каруселі

# Джерела метаданих

Метадані, що використовуються для визначення, яке обладнання потрібне для роботи програмного забезпечення, для якої вікової групи користувачів призначено програмне забезпечення, і які фактори впливають на безпеку встановлення програми, усі походять з файла metainfo програмного забезпечення.

Файл metainfo є файлом XML. Формат файла визначається специфікацією AppStream.

Див. файл metainfo для програми «Файли GNOME».

appdata застаріле позначення metainfo.

# Що трапляється, якщо метаданих не вистачає

Якщо для програми не вказано якихось метаданих, Програми можуть лише вгадувати, якими вони можуть бути, а отже не зможуть показати достатньо інформації у своєму інтерфейсі. Здогадки, які використано у Програмах, засновано на факті, що більшу частину програмного забезпечення створено для робочих станцій.

Ви можете удосконалити метадані програми!

# Як надати відомості, яких не вистачає

Якщо ви виявите, що на сторінці програми немає певних відомостей або якісь відомості є неправильними, ви можете допомогти в один з двох способів:

Ви можете повідомити про пропущені або неправильні дані у системі стеження за вадами відповідної програми, щоб їх міг виправити розробник.

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

Для обох способів вам спочатку слід знайти сторінку проєкту програми. Посилання на сторінку проєкту типово можна знайти на сторінці програми, як це показано тут. Якщо це не так, вам доведеться знайти її за допомогою простого пошуку у Google.

Код програм типово розміщується на GitLab або GitHub. Наприклад, код програм GNOME зберігається на gitlab.gnome.org.

# Як додати пропущені знімки вікон програми

Дані щодо знімків вікон програми зберігаються в елементі `<screenshots>` у тезі `<component>` програми у її файлі metainfo.

Рекомендуємо використовувати для програми від 5 до 10 знімків вікон. Ідеальні знімки вікон мають формат PNG зі співвідношенням сторін і мінімальною шириною у 620 пікселів.

Наприклад, ось записи знімків вікон для програми Програми:

<screenshots> <screenshot type="default"> <image>https://gitlab.gnome.org/GNOME/gnome-software/raw/HEAD/data/metainfo/ss-overview.png</image> <caption>Overview panel</caption> </screenshot> <screenshot> <image>https://gitlab.gnome.org/GNOME/gnome-software/raw/HEAD/data/metainfo/ss-details.png</image> <caption>Details panel</caption> </screenshot> </screenshots>

# Як виправити неправильні відомості щодо захисту та прав доступу

Відомості щодо безпеки і прав доступу для програми походять із різних джерел, залежно від того, як запаковано програму. Для традиційно запакованих програм, наприклад у форматі RPM або DEB, немає доступної інформації про безпеку чи права доступу, і ви нічого не зможете зробити, щоб додати її до програми.

Для пакунків flatpak дані беруть з маніфеста flatpak програми. Ці дані вказують на «дірки» у пісочниці, які потрібні для роботи програми. Кожна з цих «дірок» типово знижує показаний рівень захисту програми у Програмах — пересуваючи її рейтингом від «безпечної» до «потенційно небезпечної» чи «небезпечної».

Щоб удосконалити рівень захисту програми, пісочниця для неї має бути якомога щільнішою. Слід вилучити зайві права доступу у пісочниці і використати портали замість прав доступу пісочниці там, де це можливо. Використання порталів не знижує показаний рівень безпеки програми у Програмах.

Наприклад, якщо програма вимагає доступу до читання і запису в усій файловій системі (`--filesystem=host`), чи справді він їй потрібен — можливо, їй потрібен доступ до файлів у декількох певних місцях? Якщо це так, можна скористатися файловим порталом або можна визначити точніше права доступу до файлової системи.

Якщо програма працює у Wayland, а можливість роботи у X11 є лише резервною, без використання особливих можливостей X11, можливо, вона використовуватиме `--socket=fallback-x11`, а не `--socket=x11`?

Настанови щодо специфічних прав доступу або інших форматів пакування може бути додано тут пізніше.

Інформація для подальшого ознайомлення:

# Як додати пропущені відомості щодо обладнання

Дані щодо обладнання для програми зберігаються в елементах `<requires>`, `<recommends>` і `<supports>` у тезі `<component>` програми файла metainfo.

Програми обробляють елементи `<control>` і `<display_length>`.

Див. приклади метаданих у цьому або цьому дописі у блозі.

# Як додати пропущені дані щодо вікових обмежень

Дані щодо вікових обмежень програми зберігаються в елементі `<content_rating>` у тезі `<component>` програми у її файлі metainfo.

Для заповнення цього елемента слід використовувати стандарт OARS 1.1. Якщо елемент `<content_rating>` не вказано, вікові обмеження програми лишаться невідомими. Якщо елемент вказано, але він є порожнім, програма не містить нічого, що є неприпустимим для будь-якого кола користувачів.

Скористайтеся генератором OARS для створення відповідних відомостей щодо вікових обмежень для програми.

# Як виправити неправильні відомості щодо ліцензування

Дані щодо ліцензування програми зберігаються в елементі `<project_license>` у тезі `<component>` програми у її файлі metainfo.

Вмістом цього елемента має бути виразом SPDX, який описує «основну» ліцензію проєкту. Типово, це мають бути умови ліцензування коду без умов ліцензування документації або допоміжних даних.

Якщо вираз SPDX є єдиною ліцензією або об'єднанням за допомогою «or» декількох ліцензій, які усі є схваленими FSF або OSI, програма вважається «вільним програмним забезпеченням» і на плитці ліцензування буде зазначено саме це. Якщо ж це не так, програма вважатиметься «пропрієтарною».

Якщо програму показано як «пропрієтарну», а ви вважаєте, що це не так, ймовірно, до елемента `<project_license>` включено умови ліцензування документації до проєкту. Вилучіть ці умови.

Наприклад, змініть ліцензування метаданих з:

<project_license>GPL-2.0+ and CC-BY-SA-3.0</project_license>

на

<project_license>GPL-2.0+</project_license>

Інформація для подальшого ознайомлення:

Не вписуйте (загалом) ліцензування документації до appdata

# Як додати пропущені посилання

Посилання для програми зберігають як елементи `<url>` у тезі `<component>` файла metainfo програми.

Додайте якомога більше типів посилань, які документовано у специфікації appstream. Якщо відповідної сторінки для певного типу посилань немає, не слід його включати.

Наприклад, ось посилання на ресурси для програми Програми:

<url type="bugtracker">https://gitlab.gnome.org/GNOME/gnome-software/-/issues</url> <url type="contact">https://discourse.gnome.org/tag/gnome-software</url> <url type="contribute">https://welcome.gnome.org/app/Software/</url> <url type="donation">https://www.gnome.org/donate/</url> <url type="homepage">https://apps.gnome.org/Software</url> <url type="translate">https://l10n.gnome.org/module/gnome-software/</url> <url type="vcs-browser">https://gitlab.gnome.org/GNOME/gnome-software/</url>

# Як встановити колір тла плитки каруселі

Колір тла плитки для каруселі зазвичай видобувається автоматично з піктограми програми. Якщо цей колір є незадовільним, його можна перевизначити за допомогою елемента `<branding/>` appstream із оголошеними кольорами (починаючи з випусків 47.x). Перевагою є те, що кольори можна буде використовувати у ширшому діапазоні клієнтів.

Наприклад, ось деякі записи щодо бренду:

<branding> <color type="primary" scheme_preference="light">#ff00ff</color> <color type="primary" scheme_preference="dark">#993d3d</color> </branding>

Зауважте, що атрибут `scheme_preference` проігноровано, Програми виберуть кращий колір для теми автономно.

Для зворотної сумісності залишено можливість додавати такі XML для елемента `<component>` metainfo програми:

<custom> <value key="GnomeSoftware::key-colors">[(124, 53, 77), (99, 16, 0)]</value> </custom>

але елемент `<branding/>` має вищий пріоритет.

Значення `GnomeSoftware::key-colors` є GVariant у форматі тексту з типом `a(yyy)`. Воно відповідає невпорядкованому набору ключових кольорів програми. Кожен елемент набору є кольором у формі RGB у діапазоні від `(0, 0, 0)` до `(255, 255, 255)`.

Кольори слід вибирати так, щоб вони:

Були характерними для програми, певним чином відповідали бренду програми, якщо це можливо.

Були контрастними із краєм піктограми програми, щоб коли його використано як колір тло за нею, піктограму можна було розрізнити.

Були контрастними з кольором тексту у темі Adwaita (`#2e3436`) і її темним варіантом (`#eeeeec`). В основному, це означає, що слід вибрати колір із середнім рівнем яскравості.

Контрастність можна перевірити за допомогою програми «Контраст».

Слід вказати принаймні один колір. Можна вказати більше, якщо один колір не може задовольнити всім наведеним вище вимогам, і Програми виберуть найпридатніший для використання у плитці каруселі. Якщо вказано точно один колір, його яскравість і насиченість можна змінити для покращення контрастності з кольором переднього плану. Якщо вказано декілька кольорів, буде вибрано той, який найкраще контрастує з кольором переднього плану, а його яскравість і насиченість не буде змінено.

# Як виконати тестування кольору тла плитки каруселі

Внесіть зміни до файла metainfo вашої програми, а потім запустіть Програми так:

gnome-software --show-metainfo=/шлях/до/програми.metainfo.xml,icon=/шлях/до/піктограми.png

Буде показано сторінку подробиць щодо вашої програми. Якщо ви повернетеся до сторінки огляду Програм, ваша програма буде єдиною у каруселі рекомендованих.