From 3e1fd192d59baf369225d76f3702be4591e6aaf5 Mon Sep 17 00:00:00 2001
From: Mingcong Bai <jeffbai@aosc.io>
Date: Thu, 17 Oct 2024 20:06:50 +0800
Subject: [PATCH] feat(packaging): add Feature Marking Guidelines

---
 .../packaging/feature-marking-guidelines.md   | 48 +++++++++++++++++++
 .../feature-marking-guidelines.zh.md          | 34 +++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 content/developer/packaging/feature-marking-guidelines.md
 create mode 100644 content/developer/packaging/feature-marking-guidelines.zh.md

diff --git a/content/developer/packaging/feature-marking-guidelines.md b/content/developer/packaging/feature-marking-guidelines.md
new file mode 100644
index 0000000..366fd12
--- /dev/null
+++ b/content/developer/packaging/feature-marking-guidelines.md
@@ -0,0 +1,48 @@
+AOSC OS Feature Marking Guidelines
+===
+
+The Feature Marking Guidelines is designed to mark key system components that
+are not considered `Essential` per dpkg, but could be used as referenced for
+management frontends such as oma to inform users of the risks of removing
+certain packages (those that might impeded system functions and features, more
+below).
+
+With this set of guidelines, users may be better informed about the differences
+between system components and applications. This set of guidelines, by
+principle, only applies to pre-installed software.
+
+Metadata
+---
+
+- Repository- and toolchain-side: Add `X-AOSC-Features` markers to select
+  packages to indicate the relevant system features (recorded in `control` in
+  the package and `Packages` in the APT repository).
+- Introduce `aosc-os-feature-data` to record names and descriptions of the
+  system features.
+
+### Example: control and Packages
+
+`X-AOSC-Features` may contain multiple items, separated with space; the name
+of the feature items shall only contain letters a-z, numbers and dashes (-):
+
+```
+Package: plasma-workspace
+...
+X-AOSC-Features: kde-graphical-environment multimedia-playback
+```
+
+### Example: aosc-os-feature-data
+
+The `Functionality` field may be localised with the `-$LANG` suffix, those
+without a suffix will be used as the fallback (C/en_US) for systems set with
+languages without the necessary translations:
+
+```
+Feature: kde-graphical-environment
+Functionality: KDE graphical environment
+Functionality-zh_CN: KDE 图形界面
+
+Feature: multimedia-playback
+Functionality: Multimedia playback support
+Functionality-zh_CN: 多媒体播放
+```
diff --git a/content/developer/packaging/feature-marking-guidelines.zh.md b/content/developer/packaging/feature-marking-guidelines.zh.md
new file mode 100644
index 0000000..15badec
--- /dev/null
+++ b/content/developer/packaging/feature-marking-guidelines.zh.md
@@ -0,0 +1,34 @@
+安同 OS 系统特性标记规范
+===
+
+本规范用于标记 Essential 级别以下的关键系统组件，并允许 oma 等前端程序充分告知用户移除相关软件包的风险（即可能影响到的系统功能及特性，详见下文）。实现该功能是为了更直观地让用户了解系统组件及额外应用程序之间的差异，本规范原则上只涉及安同 OS 预装的软件。
+
+元数据更改
+---
+
+- 工具链及软件源侧：在 `Packages` 加入 `X-AOSC-Features`，列出相关的系统功能
+- 引入 `aosc-os-feature-data` 数据，用于记录系统功能名称及简介
+
+### 样例：control 及 Packages 元数据
+
+`X-AOSC-Features` 可包含多个子项（使用空格分割），名称只允许 a-z、数字及 -：
+
+```
+Package: plasma-workspace
+...
+X-AOSC-Features: kde-graphical-environment multimedia-playback
+```
+
+### 样例：aosc-os-feature-data
+
+`Functionality` 条目可本地化，无后缀则匹配 C/en_US（或匹配无对应翻译的系统）；后缀以 locale 语言格式（不带编码后缀）为准：
+
+```
+Feature: kde-graphical-environment
+Functionality: KDE graphical environment
+Functionality-zh_CN: KDE 图形界面
+
+Feature: multimedia-playback
+Functionality: Multimedia playback support
+Functionality-zh_CN: 多媒体播放
+```