diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 3f45086..c7d6789 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -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] diff --git a/modules/ROOT/pages/organizations_and_teams_mapping.adoc b/modules/ROOT/pages/organizations_and_teams_mapping.adoc new file mode 100644 index 0000000..164d0a7 --- /dev/null +++ b/modules/ROOT/pages/organizations_and_teams_mapping.adoc @@ -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 <> 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: `` +* Pagure Group: `fedora-` +* Pagure Namespace: `fedora-/*` + +==== Fedora Forge Structure +* **Organization**: `` (without `fedora-` prefix) +* **Team 1**: `owners` – maps to FAS group `forge--owners` with Owner permissions +* **Team 2**: `members` – maps to FAS group `` with Write permissions +* **Repositories**: All migrated projects under `` organization