Add AFP features and update documentation

.github/ISSUE_TEMPLATE/agones_feature_proposal.md

@@ -0,0 +1,34 @@
+---
+name: Agones Feature Proposal
+about: Suggest a new feature or enhancement for the Agones project.
+title: '[Feature Proposal] - <short, descriptive title>'
+labels: kind/feature, kind/operations, kind/afp
+assignees: ''
+
+---
+
+- One-line feature description (can be used as a release note):
+- Agones Feature Proposal: <!-- link to agones/feature file; if none yet, link to PR -->
+- Discussion Link: <!-- link to list thread, meeting, or recording where the feature was discussed before AFP creation -->
+- Primary contact (assignee):
+- Enhancement target (which target equals to which milestone):
+  - Alpha release target (x.y):
+  - Beta release target (x.y):
+  - Stable release target (x.y):
+- [ ] Alpha
+  - [ ] AFP update PR(s):
+  - [ ] Code update PR(s):
+  - [ ] Docs update PR(s):
+
+<!-- Uncomment these as you prepare the feature for the next stage
+- [ ] Beta
+  - [ ] AFP update PR(s):
+  - [ ] Code update PR(s):
+  - [ ] Docs update(s):
+- [ ] Stable
+  - [ ] AFP update PR(s):
+  - [ ] Code update PR(s):
+  - [ ] Docs update(s):
+-->
+
+_Please keep this description up to date. This will help the Maintainer to track the evolution of the feature efficiently._

.yamllint

@@ -49,3 +49,4 @@ ignore:
   - /site/vendor/
   - /tmp/
   - /vendor/
+  - /docs/proposals

docs/proposals/0000-afp-process/README.md

@@ -0,0 +1,309 @@
+# Agones Feature Proposal Process
+
+## Table of Contents
+
+<!-- toc -->
+- [Summary](#summary)
+- [Motivation](#motivation)
+- [Stewardship](#stewardship)
+- [Reference-Level Explanation](#reference-level-explanation)
+  - [What Type of Work Should Be Tracked by a AFP](#what-type-of-work-should-be-tracked-by-a-afp)
+  - [AFP Template](#afp-template)
+  - [AFP Metadata](#afp-metadata)
+  - [AFP Workflow](#afp-workflow)
+  - [Git and GitHub Implementation](#git-and-github-implementation)
+  - [AFP Editor Role](#afp-editor-role)
+  - [Important Metrics](#important-metrics)
+  - [Prior Art](#prior-art)
+- [Drawbacks](#drawbacks)
+- [Alternatives](#alternatives)
+  - [GitHub Issues vs. AFPs](#github-issues-vs-afps)
+- [Unresolved Questions](#unresolved-questions)
+<!-- /toc -->
+
+## Summary
+
+A standardized development process for Agones is proposed, in order to:
+
+- provide a common structure for proposing changes to Agones
+- ensure that the motivation for a change is clear
+- allow for the enumeration of stability milestones and stability graduation
+  criteria
+- persist project information in a Version Control System (VCS) for future
+  Agones
+- support the creation of _high-value, user-facing_ information such as:
+  - an overall project development roadmap
+  - motivation for impactful user-facing changes
+- reserve GitHub issues for tracking work in flight, instead of creating "umbrella"
+  issues
+- ensure community participants can successfully drive changes to
+  completion across one or more releases while stakeholders are adequately
+  represented throughout the process
+
+This process is supported by a unit of work called a Agones Feature Proposal, or AFP.
+A AFP attempts to combine aspects of
+
+- a feature, and effort-tracking document
+- a product requirements document
+- a design document
+
+into one file, which is created incrementally through collaboration with relevant stakeholders and teams.
+
+## Motivation
+
+For cross-project initiatives such as Agones, an abstraction beyond a
+single GitHub Issue or pull request seems to be required in order to understand
+and communicate upcoming changes to Agones. In a blog post describing the
+[road to Go 2][], Russ Cox explains:
+
+> that it is difficult but essential to describe the significance of a problem
+> in a way that someone working in a different environment can understand
+
+It is vital for the project to be able to track the chain of custody for a proposed
+feature from conception through implementation.
+
+Without a standardized mechanism for describing important features, our
+talented technical writers and product managers struggle to weave a coherent
+narrative explaining why a particular release is important. Additionally, adopters
+of critical infrastructure such as Agones need a forward-looking roadmap in
+order to plan their adoption strategies.
+
+The purpose of the AFP process is to reduce the amount of "tribal knowledge" in
+our community. By moving decisions from a smattering of mailing lists, video
+calls and hallway conversations into a well tracked artifact, this process aims
+to enhance communication and discoverability.
+
+A AFP is broken into sections which can be merged into source control
+incrementally in order to support an iterative development process. An important
+goal of the AFP process is ensuring that the process for submitting the content
+contained in [design proposals][] is both clear and efficient. The AFP process
+is intended to create high-quality, uniform design and implementation documents 
+to support deliberation within the project.
+
+[road to Go 2]: https://blog.golang.org/toward-go2
+[design proposals]: /docs/proposals/NNNN-afp-template
+
+## Stewardship
+The following DACI model identifies the responsible parties for AFPs.
+
+**Workstream** | **Driver** | **Approver** | **Contributor** | **Informed**
+--- | --- | --- | --- | ---
+| AFP Process Stewardship | - | - |  Project Maintainers | Community |
+| Proposal Delivery | Proposal Owner |  Project Maintainers  | Proposal Implementer(s) (may overlap with Driver) | Community |
+
+
+
+## Reference-Level Explanation
+
+### What Type of Work Should Be Tracked by a AFP
+
+The definition of what constitutes an "feature" is a foundational concern
+for the Agones project. Roughly any Agones user or operator facing
+feature should follow the AFP process. If an feature would be described
+in either written or verbal communication to anyone besides the AFP author or
+developer, then consider creating a AFP.
+
+Similarly, any technical effort (refactoring, major architectural change) that
+will impact a large section of the development community should also be
+communicated widely. The AFP process is suited for this even if it will have
+zero impact on the typical user or operator.
+
+As the local bodies of governance, project teams or contributors should have broad latitude in describing
+what constitutes an feature that should be tracked through the AFP process.
+It may be more helpful for these teams to enumerate what _does not_ require a AFP,
+than what does. Teams also have the freedom to customize the AFP template
+according to their specific concerns. For example, the AFP template used to
+track API changes will likely have different subsections than the template for
+proposing governance changes. However, as changes start impacting other areas or
+the larger developer community, the AFP process should be used to coordinate and communicate.
+
+Features that have major impacts on multiple areas of the Agones should use the AFP process.
+AFPs will also be used to drive large changes that will cut across all parts of the project.
+These AFPs will be managed by the core team and should be regarded as the primary means of communicating the most fundamental aspects of what Agones is.
+
+
+### AFP Template
+
+**The template for a AFP is precisely defined [here](/docs/proposals/NNNN-afp-template).**
+
+### AFP Metadata
+
+There is a place in each AFP for a YAML document that has standard metadata.
+This will be used to support tooling around filtering and display. It is also
+critical to clearly communicate the status of a AFP.
+
+<b>
+While this defines the metadata schema for now, these things tend to evolve.
+The AFP template is the authoritative definition of things like the metadata
+schema.
+</b>
+
+Metadata items:
+* **title** Required
+  * The title of the AFP in plain language.  The title will also be used in the
+    AFP filename.  See the template for instructions and details.
+* **status** Required
+  * The current state of the AFP.
+  * Must be one of `provisional`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
+* **authors** Required
+  * A list of authors of the AFP.
+    This is simply the GitHub ID.
+    In the future we may enhance this to include other types of identification.
+* **reviewers** Required
+  * Reviewer(s) chosen after triage, according to the proposal process.
+  * If not yet chosen, replace with `TBD`.
+  * Same name/contact scheme as `authors`.
+  * Reviewers should be a distinct set from authors.
+* **approvers** Required
+  * Approver(s) chosen after triage, according to the proposal process.
+  * Approver(s) selected based on the impacted areas or components of the project.
+    It is up to the individual areas to determine how they pick approvers for AFPs impacting them.
+    The approvers are speaking for the respective areas in the process of approving this AFP
+    The impacted areas can modify this list as necessary.
+  * The approvers are the individuals who decide when to move this AFP to the `implementable` state.
+  * Approvers should be a distinct set from authors.
+  * If not yet chosen, replace with `TBD`.
+  * Same name/contact scheme as `authors`.
+* **editor** Required
+  * Someone to keep things moving forward.
+  * If not yet chosen, replace with `TBD`.
+  * Same name/contact scheme as `authors`.
+* **creation-date** Required
+  * The date that the AFP was first submitted in a PR.
+  * In the form `yyyy-mm-dd`.
+  * While this info will also be in source control, it is helpful to have the set of AFP files stand on their own.
+* **last-updated** Optional
+  * The date that the AFP was last changed significantly.
+  * In the form `yyyy-mm-dd`.
+* **see-also** Optional
+  * A list of other AFPs that are relevant to this AFP.
+  * In the form `AFP-123`.
+* **replaces** Optional
+  * A list of AFPs that this AFP replaces.  Those AFPs should list this AFP in
+    their `superseded-by`.
+  * In the form `AFP-123`.
+* **superseded-by**
+  * A list of AFPs that supersede this AFP. Use of this should be paired with
+    this AFP moving into the `Replaced` status.
+  * In the form `AFP-123`.
+
+
+### AFP Workflow
+
+A AFP has the following states:
+
+- `provisional`: The AFP has been proposed and is actively being defined.
+  This is the starting state while the AFP is being fleshed out and actively defined and discussed.
+  The maintainer has accepted that this work must be done.
+- `implementable`: The approvers have approved this AFP for implementation.
+- `implemented`: The AFP has been implemented and is no longer actively changed.
+- `deferred`: The AFP is proposed but not actively being worked on.
+- `rejected`: The approvers and authors have decided that this AFP is not moving forward.
+  The AFP is kept around as a historical document.
+- `withdrawn`: The authors have withdrawn the AFP.
+- `replaced`: The AFP has been replaced by a new AFP.
+  The `superseded-by` metadata value should point to the new AFP.
+
+### Git and GitHub Implementation
+
+AFPs are checked into the Features repo under the `/docs/proposals` directory.
+
+New AFPs can be checked in with a file name in the form of `draft-YYYYMMDD-my-title.md`.
+As significant work is done on the AFP, the authors can assign a AFP number.
+No other changes should be put in that PR so that it can be approved quickly and minimize merge conflicts.
+The AFP number can also be done as part of the initial submission if the PR is likely to be uncontested and merged quickly.
+
+### AFP Editor Role
+
+Taking a cue from the [Kubernetes KEP process][] & [Python PEP process][], we define the role of a AFP editor.
+The job of an AFP editor is likely very similar to the [PEP editor responsibilities][] and will hopefully provide another opportunity for people who do not write code daily to contribute to Agones.
+
+In keeping with the PEP editors, who:
+
+> Read the PEP to check if it is ready: sound and complete. The ideas must make
+> technical sense, even if they don't seem likely to be accepted.
+> The title should accurately describe the content.
+> Edit the PEP for language (spelling, grammar, sentence structure, etc.), markup
+> (for reST PEPs), code style (examples should match PEP 8 & 7)
+
+AFP editors should generally not pass judgement on a AFP beyond editorial corrections.
+AFP editors can also help inform authors about the process and otherwise help things move smoothly.
+
+[Kubernetes KEP process]: https://github.com/kubernetes/enhancements/tree/master/keps
+[Python PEP process]: https://www.python.org/dev/peps/pep-0001/
+[PEP editor responsibilities]: https://www.python.org/dev/peps/pep-0001/#pep-editor-responsibilities-workflow
+
+### Important Metrics
+
+It is proposed that the primary metrics that would signal the success or
+failure of the AFP process are:
+
+- how many "features" are tracked with a AFP
+- distribution of time a AFP spends in each state
+- AFP rejection rate
+- PRs referencing a AFP merged per week
+- number of issues open which reference a AFP
+- number of contributors who authored a AFP
+- number of contributors who authored a AFP for the first time
+- number of orphaned AFPs
+- number of retired AFPs
+- number of superseded AFPs
+
+### Prior Art
+
+The AFP process, as proposed, was essentially stolen from the [Kubernetes AFP process][] & [Rust RFC process][] & [Python PEP process][].
+
+[Kubernetes AFP process]: https://github.com/kubernetes/enhancements/tree/master/afps
+[Rust RFC process]: https://github.com/rust-lang/rfcs
+
+## Drawbacks
+
+Any additional process has the potential to engender resentment within the
+community. There is also a risk that the AFP process as designed will not
+sufficiently address the scaling challenges we face today. PR review bandwidth is
+already at a premium, and we may find that the AFP process introduces an unreasonable
+bottleneck on our development velocity.
+
+It certainly can be argued that the lack of a dedicated issue/defect tracker
+beyond GitHub issues contributes to our challenges in managing a project as large
+as Agones. However, given that other large organizations, including GitHub
+itself, make effective use of GitHub issues, perhaps the argument is overblown.
+
+The centrality of Git and GitHub within the AFP process also may place too high
+a barrier to potential contributors. However, given that both Git and GitHub are
+required to contribute code changes to Agones today, perhaps it would be reasonable
+to invest in providing support to those unfamiliar with this tooling.
+
+Expanding the proposal template beyond the single-sentence description currently
+required in the [features issue template][] may be a heavy burden for non-native
+English speakers. Here, the role of the AFP editor, combined with kindness and
+empathy, will be crucial to making the process successful.
+
+[features issue template]: https://github.com/googleforgames/agones/blob/main/.github/ISSUE_TEMPLATE/feature_request.md
+
+### GitHub Issues vs. AFPs
+
+The use of GitHub issues when proposing changes does not provide an effective mechanism good
+facilities for signaling approval or rejection of a proposed change to Agones,
+because anyone can open a GitHub issue at any time. Additionally, managing a proposed
+change across multiple releases is somewhat cumbersome as labels and milestones
+need to be updated for every release that a change spans. These long-lived GitHub
+issues lead to an ever-increasing number of issues open against
+`agones/features`, which itself has become a management problem.
+
+In addition to the challenge of managing issues over time, searching for text
+within an issue can be challenging. The flat hierarchy of issues can also make
+navigation and categorization tricky. Not all community members will
+be uncomfortable using Git directly, but it is imperative for our community to educate people on a standard set of tools so they can take their
+experience to other projects they may decide to work on in the future. While
+git is a fantastic version control system (VCS), it is neither a project management
+tool nor a cogent way of managing an architectural catalog or backlog. This
+proposal is limited to motivating the creation of a standardized definition of
+work in order to facilitate project management. This primitive for describing
+a unit of work may also allow contributors to create their own personalized
+view of the state of the project while relying on Git and GitHub for consistency
+and durable storage.
+
+## Unresolved Questions
+
+- 

docs/proposals/0000-afp-process/afp.yaml

@@ -0,0 +1,18 @@
+---
+title: Agones Feature Proposal Process
+afp-number: 0000
+authors:
+  - "@0xaravindh"
+reviewers:
+  - "@markmandel"
+  - "@gongmax"
+  - "@igooch"
+approvers:
+  - "@markmandel"
+  - "@gongmax"
+  - "@igooch"
+creation-date: 2024-12-10
+last-updated: 2024-12-10
+status: provisional
+latest-milestone: '0.0'
+stage: alpha