updated central group management technical proposal

architecture/hlfs/bot-group-management.md

@@ -1,27 +1,72 @@
-# Centralized Group Management for Bots
+# Centralized Group and Maintainership Management
 
 Reference: https://github.com/openSUSE/openSUSE-git/issues/140
 
 ## Overview
 
-This document outlines a process for managing OBS group and maintainership data in a centralized Git repository. This approach provides a single source of truth for bots and other automation tools that rely on group definitions.
+This document outlines a process for managing OBS group and maintainership data in a centralized Git repository. This approach provides a single source of truth for bots and other automation tools that rely on group and maintainer definitions.
 
-## Synchronization from OBS
+## Group Synchronization from OBS
 
-- **Sync Strategy**: A standalone script will synchronize all OBS groups to a dedicated Gitea repository.
-- **Drift Detection**: A recurring job, such as a Gitea Action or cron job, will periodically check for divergences between the Gitea repository and OBS. If a drift is detected, the job will automatically open a pull request with the necessary changes.
+- **Sync Target**: A standalone script will synchronize all OBS groups to a dedicated `obs/groups` Gitea repository. This synchronization is strictly one-way, from OBS to Gitea.
+- **Storage and Format**: Each group will be stored as a separate JSON file within the repository (e.g., `my-group.json`).
+- **Data Immutability**: The synchronized group data within Gitea is considered read-only. A Gitea Action will be implemented to prevent direct modifications (e.g., commits or pull requests) to these JSON files. This enforces OBS as the single source of truth for group membership and avoids the complexity of two-way synchronization.
+- **Drift Detection**: A recurring job will periodically check for divergences between the `obs/groups` repository and OBS. If a drift is detected, the job will automatically open a pull request with the necessary changes fetched from OBS.
 
-## Data Consumption
+## Gitea-Native Groups
 
-- **Bot Consumption**: Bots will retrieve group information from files within the `obs/groups` repository. The exact file format (e.g., `GROUP_NAME.yml`) is yet to be determined.
-- **Package Maintainership**: Package ownership will be defined in a `_maintainership.json` file. This file will map packages to their respective maintainers, who can be individuals or groups.
+In addition to the groups synchronized from OBS, it is possible to define custom groups directly within Gitea to manage permissions and maintainership.
 
-  **Example `_maintainership.json`:**
-  ```json
-  {
-    "packagename": [
-      "@group_name",
-      "user_name"
-    ]
-  }
-  ```
+- **Creation**: These groups can be defined and managed in their own Git repositories.
+- **Naming Constraint**: Group names must be globally unique. A Gitea-native group **cannot** have the same name as any group synchronized from OBS.
+- **Enforcement**: A Gitea Action or pre-commit hook should be implemented to validate any new or modified Gitea-native group. This check will ensure its name does not collide with the list of existing group names from the `obs/groups` repository.
+
+## Maintainership Data Format
+
+Package and project ownership will be defined in a `_maintainership.json` file within the repository. This file will map packages to their respective maintainers, which can be individuals or groups. This self-contained format is designed to be easily parseable and self-explanatory.
+
+The format is determined by inspecting the file: if a `header` field is **not** present at the root of the JSON object, the file will be parsed as the legacy format described below. Otherwise, the new format is used.
+
+**Example `_maintainership.json` (New Format):**
+
+```json
+{
+    "header": {
+         "document": "obs-maintainers",
+         "version": "1.0"
+    },
+    "project": {
+        "users": ["project_owner1", "project_owner2"],
+        "groups": ["project-maintainer-group"]
+    },
+    "packages": {
+        "package1": {
+            "users": ["user1", "user2"],
+            "groups": ["pkg1-maintainers"]
+        },
+        "package2": {
+            "users": ["user3"],
+            "groups": ["pkg2-maintainers"]
+        }
+    }
+}
+```
+
+### Structure Explanation:
+
+*   **`header`**: Contains metadata about the file, such as the document type and version. Its presence indicates the new format.
+*   **`project`**: Defines the default owners for the entire project. This includes lists of `users` and `groups`.
+*   **`packages`**: An object containing individual entries for each package. Each package entry can specify its own list of `users` and `groups` as maintainers.
+
+### Backward Compatibility: Legacy Format
+
+The legacy format is a simple JSON object where each key represents a package name, and its value is an array of strings representing the user and group maintainers. An empty string as a key (`""`) defines project-level maintainers.
+
+**Example `_maintainership.json` (Legacy Format):**
+```json
+{
+  "": [ "project-maintainer" ],
+  "package-a": [ "user-1" ],
+  "package-b": [ "user-2" ]
+}
+```

architecture/slides/status_mvp/index.html

@@ -477,7 +477,7 @@
 
 				<!-- Slide: Useful Links -->
 				<section data-background-image="assets/other-pages.svg" data-background-size="auto">
-					<h2>Useful Links</h2>
+					<h2>Useful Resources</h2>
 					<ul style="text-align: left; font-size: 0.9em;">
 						<li><strong>GitHub Kanban Board:</strong> <a href="https://github.com/orgs/openSUSE/projects/11/views/1?filterQuery=label%3AMVP">https://github.com/orgs/openSUSE/projects/11</a></li>
 						<li><strong>GitHub Issues:</strong> <a href="https://github.com/openSUSE/openSUSE-git/issues">https://github.com/openSUSE/openSUSE-git/issues</a></li>
@@ -486,6 +486,7 @@
 						<li><strong>obs-scm-bridge documentation:</strong> <a href="https://openbuildservice.org/help/manuals/obs-user-guide/cha-obs-scm-bridge">https://openbuildservice.org/help/manuals/obs-user-guide/cha-obs-scm-bridge</a></li>
 						<li><strong>External Documentation:</strong> <a href="https://src.opensuse.org/openSUSE/git-workflow-documentation">https://src.opensuse.org/openSUSE/git-workflow-documentation</a></li>
 						<li><strong>Internal Documentation:</strong> <a href="https://src.suse.de/SUSE/git-workflow-documentation">https://src.suse.de/SUSE/git-workflow-documentation</a></li>
+						<li><strong>Slack Channels:</strong> #proj-framework-one and #proj-framework-one-git-packaging</li>
 					</ul>
 				</section>