Add organizations and teams mapping documentation

- Document relationship between Organizations and Teams in Fedora Forge
- Explain mapping from Pagure.io concepts to Forgejo structure
- Provide Rust organization migration example with standard FAS group naming
- Link to FAS Group Naming Standards for exception cases
- Add to User Documentation navigation
This commit is contained in:
Ryan Lerch 2025-10-06 07:59:26 +10:00
commit ab125abc9b
2 changed files with 63 additions and 0 deletions

View file

@ -1,6 +1,7 @@
* User Documentation
** xref:create_org_profile_page.adoc[How to create an Organization Front Page]
** xref:requesting_new_org_or_team.adoc[Requesting a New Organization and/or Team]
** xref:organizations_and_teams_mapping.adoc[Organizations and Teams Mapping]
** xref:using_http_auth.adoc[How to Clone a Repo with HTTPS]
** xref:issue_pull_request_templates.adoc[Issue and Pull Request Templates]
** xref:migration/pagure.adoc[Migrating from Pagure]

View file

@ -0,0 +1,62 @@
= Organizations and Teams Mapping for Fedora Forge
[WARNING]
====
**DRAFT DOCUMENTATION:** This documentation is currently in draft form and may not be fully tested and correct. Please verify all procedures before use and report any issues or inaccuracies.
====
== Overview
This document explains the relationship between Organizations and Teams in Fedora Forge, and how they map to concepts from Pagure.io. Understanding this mapping is crucial for teams migrating from Pagure.io to Fedora Forge.
== Organizations vs Teams
=== What's the difference between an Organization and a Team?
**Organizations** are the top-level containers that group related repositories together - they represent the "namespace" or "group" concept from Pagure.io. Organizations themselves don't have permissions - they're just containers. Examples would be `rust`, `infrastructure`, or `council`.
**Teams** are permission groups within an Organization that define who can do what. They control access to repositories within an Organization and have specific permission levels (Read, Write, Admin, Owner). Examples would be `owners`, `contributors`, or `members`.
Think of it this way: **Organization** = The "SIG" or "team" or "subproject", and **Team** = The "roles" within that SIG/team/subproject.
You need both because Organizations provide the namespace structure (like Pagure.io namespaces) while Teams provide the permission management (like Pagure.io group permissions).
== Migration Mapping Examples
=== Rust Organization Example
Based on a typical Rust organization migration, here's how the mapping would work:
==== Current Pagure.io Setup
* FAS Group: `rust-sig`
* Pagure Group: `fedora-rust`
* Pagure Namespace: `fedora-rust/*`
* Permissions: `fedora-rust` group has admin access to most projects
==== Recommended Forgejo Setup
* **Organization**: `rust`
* **Team 1**: `owners` maps to FAS group `forge-rust-owners` with Owner permissions
* **Team 2**: `members` maps to FAS group `forge-rust-members` with Write permissions
* **Repositories**: All migrated `fedora-rust/*` projects under `rust` organization
[NOTE]
====
The `forge-` convention is used for new FAS groups, but existing FAS groups can be reused when appropriate. See the <<Exception Cases>> section in xref:fas_group_naming_standards.adoc[FAS Group Naming Standards] for details.
====
=== General Migration Pattern
For most Pagure.io migrations, the pattern follows:
==== Pagure.io Structure
* FAS Group: `<team-name>`
* Pagure Group: `fedora-<team-name>`
* Pagure Namespace: `fedora-<team-name>/*`
==== Fedora Forge Structure
* **Organization**: `<team-name>` (without `fedora-` prefix)
* **Team 1**: `owners` maps to FAS group `forge-<team-name>-owners` with Owner permissions
* **Team 2**: `members` maps to FAS group `<team-name>` with Write permissions
* **Repositories**: All migrated projects under `<team-name>` organization