Add Fedora Accounts groups and Forge team naming documentation

- Document Fedora Accounts groups, Forge organizations, and team naming
- Explain that owners team is mandatory (Forgejo requirement), not specifically the Fedora Accounts group
- Document flexible team naming with examples (docs teams: quick-docs-writers, etc.)
- Document organization naming (no fedora- prefix, no -sig suffix)
- Document examples for council, releng, and docs organizations
- Document exception cases for reusing existing groups like council
This commit is contained in:
Ryan Lerch 2025-10-06 07:27:05 +10:00
commit c61c013efb
2 changed files with 221 additions and 0 deletions

View file

@ -12,6 +12,7 @@
* Admin Documentation
** xref:creating_a_new_org.adoc[Creating a new Organization]
** xref:creating_a_new_team.adoc[Creating a new Team]
** xref:fas_group_naming_standards.adoc[FAS Group Naming Standards]
* Known Issues
** xref:known_issue_cannot_create_user.adoc[Unable to Log in - "Cannot Create Account"]
** xref:known_issue_organization_projects.adoc[Adding Issues to Organization Projects Doesn't "Stick"]

View file

@ -0,0 +1,220 @@
= Fedora Accounts Groups, Forge Organizations, and Team Naming Standards
[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 establishes the standard naming conventions for Fedora Accounts groups, Fedora Forge organizations, and team names used in Fedora Forge. Consistent naming helps administrators create appropriately named groups and organizations, and helps contributors understand what access different groups provide.
== Standard Naming Convention
=== Organization Naming
Fedora Forge organizations should use short, descriptive names without the "fedora-" prefix. Since Fedora Forge only contains Fedora-related projects, the "fedora-" prefix would be redundant. Similarly, avoid using suffixes like "-sig" in organization names - use the core descriptive name instead.
**Examples**:
* `docs` (not `fedora-docs`)
* `releng` (not `fedora-releng`)
* `websites` (not `fedora-websites`)
* `rust` (not `rust-sig`)
* `python` (not `python-sig`)
=== Fedora Accounts Group Naming
**Primary Pattern**: `forge-<organization>-<team>`
**Format**: `forge-<organization-name>-<team-name>`
**Components**:
* **Prefix**: `forge-` (required for all Fedora Forge-specific groups)
* **Organization Name**: The name of the Fedora Forge organization (lowercase, hyphenated, without "fedora-" prefix)
* **Team**: The team name within the organization. This suffix should typically match the team name as it appears in the Forgejo organization (in Forgejo vernacular, this is what defines the group's purpose and permissions)
[NOTE]
====
For cases where the standard naming pattern may not apply, see <<Exception Cases>> below.
====
=== Team Naming Standards
Teams within Forgejo organizations should use descriptive names that clearly indicate their purpose and scope. Team names should be lowercase and use hyphens for word separation.
==== Mandatory Teams
[cols="1,2,2"]
|===
|Team |Purpose |Forgejo Permissions
|`owners`
|Organization administrators (**required by Forgejo software**)
|Full organization management, repository creation, team management
|===
==== Common Optional Teams
While `owners` is the only mandatory team, organizations typically also create:
[cols="1,2,2"]
|===
|Team |Purpose |Forgejo Permissions
|`members`
|Standard contributors
|Repository access based on team assignments
|===
==== Flexible Team Naming
Organizations can create teams with descriptive names to match their workflow needs. Organization administrators can configure specific permissions and repository access for each team.
**Examples of custom team names**:
* Documentation teams: `quick-docs-writers`, `guide-writers`, `release-notes-writers`
* Development teams: `maintainers`, `reviewers`, `testers`
* Special purpose teams: `security-team`, `localization`, `packagers`
[IMPORTANT]
====
Organization administrators have full control over team permissions in Forgejo, including:
* Repository read/write access per team
* Issue and pull request permissions
* Wiki and other feature access
* Custom permission combinations for specialized workflows
====
== Examples
=== Council Organization
[cols="1,1,1"]
|===
|Fedora Accounts Group |Forgejo Organization |Team
|`forge-council-owners`
|`council`
|`owners`
|`council`
|`council`
|`members`
|===
[NOTE]
====
This is an exception case where the existing `council` Fedora Accounts group is reused for the Members team instead of following the standard `forge-<org-name>-members` pattern. See <<Exception Cases>> for details.
====
=== Releng Organization
[cols="1,1,1"]
|===
|Fedora Accounts Group |Forgejo Organization |Team
|`forge-releng-owners`
|`releng`
|`owners`
|`forge-releng-members`
|`releng`
|`members`
|===
=== Docs Organization
[cols="1,1,1"]
|===
|Fedora Accounts Group |Forgejo Organization |Team
|`forge-docs-owners`
|`docs`
|`owners`
|`forge-docs-members`
|`docs`
|`members`
|`forge-docs-quick-docs-writers`
|`docs`
|`quick-docs-writers`
|`forge-docs-guide-writers`
|`docs`
|`guide-writers`
|`forge-docs-release-notes-writers`
|`docs`
|`release-notes-writers`
|===
== Naming Rules
=== Required Elements
. **Prefix**: All groups MUST start with `forge-`
. **Organization Name**: Must match the Fedora Forge organization name exactly (lowercase, without "fedora-" prefix)
. **Team Suffix**: Must include at minimum an `owners` team (Forgejo requirement). Additional teams can use any descriptive name that follows formatting guidelines and should typically match the team name as it appears in the Forgejo organization.
=== Formatting Guidelines
. **Lowercase Only**: All group names must be lowercase
. **Hyphen Separation**: Use hyphens (`-`) to separate components
. **No Underscores**: Do not use underscores (`_`) in group names
. **No Spaces**: Group names cannot contain spaces
== Fedora Accounts Groups and Team Naming Requirements
=== For New Organizations
When requesting a new organization, the **owners** team is mandatory (Forgejo software requirement). This typically requires creating a corresponding Fedora Accounts group:
* `forge-<org-name>-owners` (**required** Fedora Accounts group for organization administration)
Additional recommended Fedora Accounts groups:
* `forge-<org-name>-members` (recommended for general team membership)
Optional custom Fedora Accounts groups based on organizational needs:
* `forge-<org-name>-<descriptive-team-name>` (custom groups for teams with specific purposes)
[NOTE]
====
Organization administrators can create additional teams after the organization is established and configure specific permissions for each team through the Forgejo interface.
====
=== Fedora Accounts Group Membership Guidelines
* **Owners Group**: Must include organization administrators and project leads (corresponds to mandatory owners team)
* **Members Group**: Should include all contributors who need basic repository access (common pattern)
* **Custom Groups**: Should have clear purposes and appropriate members based on their specialized team function
* **Nested Membership**: Consider having owners as members of broader groups when appropriate for workflow
== Exception Cases
=== Reusing Existing Groups
In some cases, existing Fedora Accounts groups may be reused instead of creating new forge-specific groups:
**When to Reuse**:
* The existing group perfectly matches the intended purpose
* The group is already widely used by the team
* Administrative overhead reduction is beneficial
**Examples of Acceptable Reuse**:
* `council` instead of `forge-council-members` (for Fedora Council)
* `releng` instead of `forge-releng-members` (for existing Release Engineering team)
== Related Documentation
* xref:creating_a_new_org.adoc[Creating a New Organization]
* xref:creating_a_new_team.adoc[Creating a New Team]
* xref:requesting_new_org_or_team.adoc[Requesting New Organizations/Teams]