Proposed RFC: Merge access control and designated ownership of o3de/o3de.org

[sptramer]

When presented in italics, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF RFC 2119.

Clarification of website section ownership

This RFC is to establish a system where we can separate out different maintainers and owners of the o3de.org website. Currently, sig-docs-community ("the SIG") is managing all sections of the website under the policy of requiring two reviewers, which impacts things like our ability to publish content that documentation reviewers shouldn't need to be involved in.

This RFC is a proposal to create the following:

• A set of representative groups which maintain either GitHub organizations or groups within the O3DE project that can be assigned to approve issues, directly submit repo changes without approval (in high-severity events), or participate in review processes outside of sig-docs-community norms or without the participation of the SIG. The following groups are suggested to start:
  • sig-dc-documentation reviewer and maintainer groups, who have permissions to review and change content/docs, content/community, and content/contribute as well as the associated media and layouts.
  • sig-dc-community reviewer and maintainer groups, who have permissions to review and change content/blog, content/community/, content/contribute, and the associated media and layouts. Community changes should have at least one approver from sig-docs-community outside this group, which would be a process change.
  • o3df-representatives, a group of representatives from the Open 3D Foundation. At minimum, this group should have permission to static/img and layouts/partials for the management of logos, partners, and events. The Foundation may also be required to review certain content before going live.
  • o3de-website, a group dedicated to the maintenance and development of the o3de.org website. This group should have access to all HTML, JS, CSS/SASS, and other webdev-related file types. The website group must not have permission to merge docs.
• An enforcement mechanism for these restrictions. GitHub CODEOWNERS support is recommended.

Note that the representative groups are not mutually exclusive. We expect that there will be crossover between documentation and blog reviewers, for example; Documentation will likely want to provide (or require) copyedit support for blogs.

NOTE: This RFC does not affect technical review processes. Technical reviewers must not have merge permissions on o3de.org and should participate in review on a case-by-case basis.

What is the relevance of this feature?

Currently, there are a number of situations in which sig-docs-community reviewers and maintainers are blockers on critical items, such as o3de/o3de.org#1799 (Press releases and announcements) or o3de/o3de.org#1836 (materials owned and managed by the Open 3D Foundation / Linux Foundation). In addition, there have been a number of kind/website or kind/foundation issues coming up during sig-docs-community triage.

We need to effectively delegate responsibilities to other organizations and projects where documentation approval should not or must not be a blocker. In addition, as the website becomes more complicated and undergoes active development, it's important to remember that sig-docs-community should not be the current owner of website development as covered in sig-docs-community charter due to the SIG's lack of ownership of "website UX", which is also not part of the scope of the sig-ui-ux charter.

In addition to establishing these groups, their permissions and access control for the GitHub repository settings need to be enforced. Further details on enforcement are located in the "Feature Design Description - Enforcement mechanism" section.

What are the advantages of the feature?

• Clearly delegate roles and responsibilities for ownership of website areas.
• Prevents non-representative groups from committing to (or reviewing) areas of non-ownership.
• Removes sig-docs-community/reviewers and maintainers group from involvement in changes unrelated to documentation.
• Provides an official channel for the Open 3D Foundation to manage their access control to the o3de.org repo.
• Provides a delegated group which can review website code changes.
• Provides a delegated group which can submit and publish blogs under their own system.
• Sets up a system of infrastructure for additional groups, projects, or stakeholder teams for the website as needed.
• Uses a standard enforcement mechanism for review and write access requirements on GitHub.

What are the disadvantages of the feature?

• Creates the additional bureaucracy of multiple stakeholder groups in some approval processes, which may actually slow them down.
• "Community" and "Website" reviewer groups will need to amend the reviewers-maintainers governance.
• Further muddies some of the confusion around ownership of the website experience in the sig-docs-community charter. The SIG proposed website-dev as a maintainer group and will need to collaborate with it.
• Proposed code ownership mechanisms may prove to be too restrictive for certain groups to operate effectively.

Feature design description

This section outlines four areas of feature design: Group responsibilities, enforcement mechanisms, ownership mapping, and SIG changes.

Distinct groups and responsibilities

The major areas we've identified where there should be specialized stakeholders in addition to the documentation group are:

• Community reviewers; Reviewers responsible for handling non-documentation materials related to community interactions, contribution, and information. This includes materials like the o3de.org README.md and CONTRIBUTING files, in addition to blog posts and the website /community content.
• Web development; Web developers must not touch documentation while documentation, blog teams, and the foundation may need to edit website code (such as shortcodes or templates for documentation to fix UX errors, or change information architecture.) Individual SIGs or the Foundation may review website changes where appropriate, but web developers must not review documentation changes.
• The Open 3D Foundation; The Foundation itself should not only have a high level of authority to act upon the repository, but also must be the designated owner of certain materials such as any partner lists, logo images, or press releases they choose to post on o3de.org. They also must be able to respond to any urgent request related to o3de.org.

These groups should be named sensibly in accordance with O3DE group naming guidelines. We recommend:

• Docs reviewers / maintainers: o3de/docs-reviewers and o3de/docs-maintainers - Existing groups that do not need a rename.
• Community reviewers / maintainers: o3de/community-reviewers and o3de/community-maintainers - New groups analogous to o3de/docs-* but specifically for community and blog content.
• Foundation representatives: o3de/lf - This is an existing group. If the Foundation would like to make website access more restrictive, they are welcome to request a change.
• Website development: o3de/website-dev - A new group specifically for website maintenance.

Enforcement mechanism

The recommended enforcement mechanism is GitHub CODEOWNERS. This feature is already in use on o3de/o3de to designate feature ownership by SIG, and to ensure that reviewers are automatically assigned when appropriate.

GitHub CODEOWNERS file support exists explicitly to support the use case that this RFC is addressing.

Group ownership mappings in repository

The following tables describe which groups have merge privileges on which files. Files which the group has merge privileges to must participate in review, and each ownership group must establish appropriate review policies. For files with more than one group with merge permissions, one reviewer from each group with merge permissions (except the LF) should be required for merge.

Note: The Linux Foundation/O3DF group is only listed in this chart for files which they are required to review. Otherwise, they must have complete merge control over the entire repository, due to being the designated corporate owners of O3DE and their ownership of incident response.

Group	Merge permissions
docs-reviewers	content/docs/*
	content/smoketest.md
	static/docs/*
	static/_redirects
	static/images/api-reference/*
	static/images/atom-guide/*
	static/images/community/*
	static/images/contribute/*
	static/images/contributing/*
	static/images/learning-guide/*
	static/images/release-notes/*
	static/images/shared/*
	static/images/tools-ui/*
	static/images/user-guide/*
	static/images/welcome-guide/*
	static/images/icons/*
	layouts/shortcodes/*
	layouts/docs/*
	layouts/partials/docs*
community-reviewers	content/blog/*
	content/community/*
	content/contribute/*
	content/docs/contributing/*
	static/images/blog/*
	static/images/community/*
	static/images/contribute/*
	static/images/contributing/*
	static/images/shared/*
	layouts/blog/*
	layouts/community/*
	layouts/contribute/*
	layouts/partials/blog/*
	layouts/partials/community/*
	layouts/partials/contribute/*
	layouts/partials/blog-display.html
	layouts/partials/css.html
	CONTRIBUTING
	README.md
website-dev	assets/*
	layouts/*
	content/search/*
	static/js/*
	config.toml
	Makefile
	package.json
foundation	content/download/*
	content/_index.md
	LICENSE-*
	_index.md
	netlify.toml
	static/apple-touch-icon-114x114.png
	static/apple-touch-icon-120x120.png
	static/apple-touch-icon-144x144.png
	static/apple-touch-icon-152x152.png
	static/apple-touch-icon-180x180.png
	static/apple-touch-icon-57x57.png
	static/apple-touch-icon-72x72.png
	static/apple-touch-icon-76x76.png
	static/apple-touch-icon.png
	static/favicon.ico
	static/img/*
	static/images/events/*
	static/images/home/*

Required changes for Documentation & Community SIG

If this RFC is accepted, there will be some additional requirements for the SIG to take up as official business, and must involve representatives from each newly formed group to address the following concerns:

• Requirements to become a "community" reviewer or maintainer, as an amendment to reviewers-maintainers.
• Requirements to become a "web developer" reviewer or maintainer, as an amendment to reviewers-maintainers.
• Clarification of ownership of specific website elements or features as owned by the SIG, Open 3D Foundation, or the web developer group. This should be proposed as an amendment to the current sig-docs-community charter.
• Review guidelines and policies for each newly created group.

Technical considerations

The only technical consideration is the enforcement mechanism for access control. GitHub CODEOWNERS remains the most viable solution.

Scope of work

The scope of work is summarized best as:

1. Setting up the appropriate GitHub organizations or groups.
2. Creating and maintaining a CODEOWNERS file. This file will change if the group organization changes, or if the repository is restructured or changed in some way that requires adding or removing access control.
3. Amending SIG documents in a timely fashion.

All of these processes are more or less known quantities from an operational standpoint (1, 2) or have well-established processes if not exactly an understood scope of effort (3). A more or less complete description of what would be assigned via CODEOWNERS is contained within this RFC.

Are there any alternatives to this feature?

The only considered alternative at this time is to continue operating with a single reviewer and owner group, under the current charter and reviewer/maintainer roles. Alternate suggestions to the proposal outlined in this RFC are more than welcome.

Are there any open questions?

• Press releases from Open 3D Foundation: An additional consideration is whether or not the Open 3D Foundation should publish press releases through the o3de.org website as opposed to o3d.foundation. Since press releases are published in the blog/ section, under SIG rules, they would require review from the community group. Relying on open source contributors for timely merging of press releases or coordinated information from the Foundation should be a concern.
• Foundation representative access requirements. The foundation may require stricter access controls than only o3de/lf, or may have additional requests that they would submit outside of the RFC process as part of their ownership of the Open 3D Engine project.
• Impending website redesign. Content may get reorganized or undergo further refinement of ownership during a website redesign. We will need to come up with an appropriate file mapping and possibly a further breakdown in partnership with web developers.

[willihay]

I've read and support this proposal.

One question for clarification: In the first part of the RFC, you list a set of representative groups, e.g. sig-dc-documentation and o3df-representatives. How are these group names used in practice? Are they for mailing lists? Access control? I'm not sure what purpose they serve when we have the groups that are mentioned later in the RFC such as o3de/docs-reviewers and o3de/lf.

[sptramer]

One question for clarification: In the first part of the RFC, you list a set of representative groups, e.g. sig-dc-documentation and o3df-representatives. How are these group names used in practice? Are they for mailing lists? Access control? I'm not sure what purpose they serve when we have the groups that are mentioned later in the RFC such as o3de/docs-reviewers and o3de/lf.

Access control only; The RFC should have been clearer in the summary as to what those generalized groups map to. Here's the list:

• sig-dc-documentation -> The GitHub groups o3de/docs-reviewers and o3de/docs-maintainers
• o3df-representatives -> Currently o3de/lf; This requires some feedback from the Foundation on whether or not they require a different GitHub group for tighter access control on the website.
• sig-dc-community -> o3de/community-reviewers and o3de/community-maintainers, managers of the community-focused content. These groups would almost certainly need permissions on https://github.com/o3de/community as well.
• o3de-website -> o3de/website-reviewers and o3de/website-maintainers, new groups specifically for the website maintenance.

[chanmosq]

I've read and support this proposal as well.

[chanmosq]

Upon acceptance, this RFC should also involve updating the SIG Docs and Community Charter to accurately distinguish sig-docs-community's responsibilities. Who's responsible for what parts of the website can easily get fuzzy, so the charter should clarify that.

[chanmosq]

On hold, need feedback from Linux Foundation

[sptramer]

Feedback during release: We also need a designated review/merge process for the content/docs/release-notes directory. I'd propose that this be owned strictly by sig-docs-community chairs and a set of representatives from sig-release. In addition, the policy would allow sig-release activity only on stabilization/version branches.

Owners of release notes on stabilization/version branches

• sig-docs-community chairs or a delegated maintainer
• sig-release maintainers, chairs, or release managers (at the discretion of sig-release)

Owners of release notes on all other branches

• sig-docs-community chairs only. Release notes should not be updated outside of a release period under the current release policies.

Enforcement changes

This means that the CODEOWNERS mechanism will need to be maintained separately on stabilization branches as part of creating them. This would need to become part of an official release process checklist.

cc @o3de/sig-release

[chanmosq]

We'll leave this open for further review one more week. The last day to address this is Friday Oct. 28

[chanmosq]

This RFC has been accepted. Acceptance took place at sig-docs-community meeting on 11/09/2022.

[sptramer]

Action items:

• Add CODEOWNERS o3de.org#2097
• Set up process for maintenance of o3de.org CODEOWNERS during stabilization/release sig-release#108
• Guidance needed: Reviewers/maintainers of release notes sig-release#109
• Message acceptance of RFC #61 #75
• Draft new reviewer guidelines: docs-reviewer, community-reviewer, web-reviewer, and baseline tech reviewer rules/template #76