agones.dev/agones@v1.53.0/docs/proposals/README.md (about)

     1  # Agones Feature Proposals (AFPs)
     2  
     3  A Agones Feature Proposal (AFP) is a way to propose, communicate and coordinate on new efforts for the Agones project.
     4  
     5  ## Table of Contents
     6  
     7  <!-- toc -->
     8  - [Summary](#summary)
     9  - [Motivation](#motivation)
    10  - [Stewardship](#stewardship)
    11  - [Reference-Level Explanation](#reference-level-explanation)
    12    - [What Type of Work Should Be Tracked by a AFP](#what-type-of-work-should-be-tracked-by-a-afp)
    13    - [AFP Template](#afp-template)
    14    - [AFP Metadata](#afp-metadata)
    15    - [AFP Workflow](#afp-workflow)
    16    - [Git and GitHub Implementation](#git-and-github-implementation)
    17    - [AFP Editor Role](#afp-editor-role)
    18  - [Drawbacks](#drawbacks)
    19  - [FAQs](#faqs)
    20  <!-- /toc -->
    21  
    22  ## Summary
    23  
    24  A standardized development process for Agones is proposed, in order to:
    25  
    26  - provide a common structure for proposing changes to Agones
    27  - ensure that the motivation for a change is clear
    28  - persist project information in a Version Control System (VCS) for future
    29    Agones
    30  - support the creation of _high-value, user-facing_ information such as:
    31    - an overall project development roadmap
    32    - motivation for impactful user-facing changes
    33  - reserve GitHub issues for tracking work in flight, instead of creating "umbrella"
    34    issues
    35  - enable community participants to drive changes effectively across multiple releases 
    36    while ensuring stakeholder representation throughout the process.
    37  
    38  This process is supported by a unit of work called a Agones Feature Proposal, or AFP.
    39  A AFP attempts to combine aspects of
    40  
    41  - a feature, and effort-tracking document
    42  - a product requirements document
    43  - a design document
    44  
    45  These are created incrementally through collaboration with relevant stakeholders and teams.
    46  
    47  ## Motivation
    48  
    49  Currently, design discussions in Agones primarily occur as comments on GitHub issues. 
    50  While this provides flexibility, it can also lead to confusion and inefficiencies. 
    51  For example, design discussions may be fragmented, causing difficulty in tracking 
    52  updates and providing feedback on lengthy designs.
    53  
    54  To improve clarity, the AFP process introduces a more structured way to propose and 
    55  track changes. This process is inspired by Kubernetes' KEP process and is designed 
    56  to be lightweight while supporting high-quality, uniform design and implementation documents.
    57  
    58  ## Stewardship
    59  The following DACI model identifies the responsible parties for AFPs.
    60  
    61  **Workstream** | **Driver** | **Approver** | **Contributor** | **Informed**
    62  --- | --- | --- | --- | ---
    63  | AFP Process Stewardship | - | - |  Project Maintainers | Community |
    64  | Proposal Delivery | Proposal Owner |  Project Maintainers  | Proposal Implementer(s) (may overlap with Driver) | Community |
    65  
    66  ## Reference-Level Explanation
    67  
    68  ### What Type of Work Should Be Tracked by a AFP
    69  
    70  The definition of what constitutes a "feature" is essential for the Agones project. 
    71  Generally, any Agones user or operator-facing feature should follow the AFP process. This includes:
    72  
    73  - Features that impact users or operators.
    74  - Technical efforts such as refactoring or major architectural changes that impact a broad section of the development community.
    75  
    76  The AFP process should be used to communicate changes that impact multiple areas of Agones or 
    77  involve major cuts across the entire project.
    78  
    79  ### AFP Template
    80  
    81  **The template for a AFP is precisely defined [here](/docs/proposals/NNNN-afp-template).**
    82  
    83  ### AFP Metadata
    84  
    85  There is a place in each AFP for a YAML document that has standard metadata.
    86  This will be used to support tooling around filtering and display. It is also
    87  critical to clearly communicate the status of a AFP.
    88  
    89  <b>
    90  While this defines the metadata schema for now, these things tend to evolve.
    91  The AFP template is the authoritative definition of things like the metadata
    92  schema.
    93  </b>
    94  
    95  Metadata items:
    96  * **title** Required
    97    * The title of the AFP in plain language. The title will also be used in the
    98      AFP filename.  See the template for instructions and details.
    99  * **status** Required
   100    * The current state of the AFP.
   101    * Must be one of `provisional`, `implementable`, `implemented`, `deferred`, `rejected`, `withdrawn`, or `replaced`.
   102  * **authors** Required
   103    * A list of authors of the AFP.
   104      This is simply the GitHub ID.
   105      In the future we may enhance this to include other types of identification.
   106  * **reviewers** Required
   107    * Reviewer(s) chosen after triage, according to the proposal process.
   108    * Reviewer(s) selected based on the impacted areas or components of the project.
   109      It is up to the individual areas to determine how they pick reviewers for AFPs impacting them.
   110      The reviewers are speaking for the respective areas in the process of approving this AFP
   111      The impacted areas can modify this list as necessary.
   112    * The reviewers are the individuals who decide when to move this AFP to the `implementable` state.
   113    * If not yet chosen, replace with `TBD`.
   114    * Same name/contact scheme as `authors`.
   115  * **editor** Required
   116    * Someone to keep things moving forward.
   117    * If not yet chosen, replace with `TBD`.
   118    * Same name/contact scheme as `authors`.
   119  * **creation-date** Required
   120    * The date that the AFP was first submitted in a PR.
   121    * In the form `yyyy-mm-dd`.
   122    * While this info will also be in source control, it is helpful to have the set of AFP files stand on their own.
   123  * **last-updated** Optional
   124    * The date that the AFP was last changed significantly.
   125    * In the form `yyyy-mm-dd`.
   126  * **see-also** Optional
   127    * A list of other AFPs that are relevant to this AFP.
   128    * In the form `AFP-123`.
   129  * **replaces** Optional
   130    * A list of AFPs that this AFP replaces. Those AFPs should list this AFP in
   131      their `superseded-by`.
   132    * In the form `AFP-123`.
   133  * **superseded-by**
   134    * A list of AFPs that supersede this AFP. Use of this should be paired with
   135      this AFP moving into the `Replaced` status.
   136    * In the form `AFP-123`.
   137  
   138  ### AFP Workflow
   139  
   140  A AFP has the following states:
   141  
   142  - `provisional`: The AFP has been proposed and is actively being defined.
   143    This is the starting state while the AFP is being fleshed out and actively defined and discussed.
   144    The maintainer has accepted that this work must be done.
   145  - `implementable`: The reviewers have approved this AFP for implementation.
   146  - `implemented`: The AFP has been implemented and is no longer actively changed.
   147  - `deferred`: The AFP is proposed but not actively being worked on.
   148  - `rejected`: The reviewers and authors have decided that this AFP is not moving forward.
   149    The AFP is kept around as a historical document.
   150  - `withdrawn`: The authors have withdrawn the AFP.
   151  - `replaced`: The AFP has been replaced by a new AFP.
   152    The `superseded-by` metadata value should point to the new AFP.
   153  
   154  ### Git and GitHub Implementation
   155  
   156  AFPs are checked into the repository under the `/docs/proposals` directory.
   157  
   158  New AFPs should be checked in with a folder name in the form of `00x-feature-name`, where 
   159  "00x" represents an incremental AFP number. The corresponding pull request (PR) should be titled 
   160  in the format `AFP-00x`, matching the folder naming convention.
   161  
   162  As significant work is done on the AFP, the authors can assign an AFP number. No other changes 
   163  should be included in that PR so that it can be approved quickly and minimize merge conflicts. 
   164  The AFP number can also be assigned as part of the initial submission if the PR is likely to 
   165  be uncontested and merged quickly.
   166  
   167  ### AFP Editor Role
   168  
   169  Taking a cue from the [Kubernetes KEP process][] & [Python PEP process][], we define the role of a AFP editor.
   170  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.
   171  
   172  In keeping with the PEP editors, who:
   173  
   174  > Read the PEP to check if it is ready: sound and complete. The ideas must make
   175  > technical sense, even if they don't seem likely to be accepted.
   176  > The title should accurately describe the content.
   177  > Edit the PEP for language (spelling, grammar, sentence structure, etc.), markup
   178  > (for reST PEPs), code style (examples should match PEP 8 & 7)
   179  
   180  AFP editors should generally not pass judgement on a AFP beyond editorial corrections.
   181  AFP editors can also help inform authors about the process and otherwise help things move smoothly.
   182  
   183  [Kubernetes KEP process]: https://github.com/kubernetes/enhancements/tree/master/keps
   184  [Python PEP process]: https://www.python.org/dev/peps/pep-0001/
   185  [PEP editor responsibilities]: https://www.python.org/dev/peps/pep-0001/#pep-editor-responsibilities-workflow
   186  
   187  ## Drawbacks
   188  
   189  Introducing the AFP process may initially add extra steps that could frustrate some community members. 
   190  It could also introduce bottlenecks, particularly during the review and approval stages. 
   191  However, the structure and clarity provided by AFPs will ultimately benefit larger, more complex projects like Agones.
   192  
   193  While GitHub issues serve as a way to track changes, they can become cumbersome for managing 
   194  long-term proposals and discussions. The AFP process aims to address these limitations by providing 
   195  a more organized and structured approach.
   196  
   197  ## FAQs
   198  
   199  ### Do I have to use the AFP process?
   200  
   201  More or less, yes.
   202  
   203  Having a rich set of AFPs in one place will make it easier for people to track
   204  what is going in the community and find a structured historical record.
   205  
   206  AFPs are required for most non-trivial changes.  Specifically:
   207  * Anything that may be controversial
   208  * Most new features (except the very smallest)
   209  * Major changes to existing features
   210  * Changes that are wide ranging or impact most of the project (these changes
   211    are usually coordinated through the relevant maintainers)
   212  
   213  Beyond these, it is up to the team to decide when they want to use the AFP 
   214  process. It should be light-weight enough that AFPs are the default position.
   215  
   216  ### Why would I want to use the AFP process?
   217  
   218  Our aim with AFPs is to clearly communicate new efforts to the Agones contributor community.
   219  As such, we want to build a well curated set of clear proposals in a common format with useful metadata.
   220  
   221  Benefits to AFP users (in the limit):
   222  * Cross indexing of AFPs so that users can find connections and the current status of any AFP.
   223  * A clear process with and reviewers for making decisions.
   224    This will lead to more structured decisions that stick as there is a discoverable record around the decisions.
   225  
   226  ### What will it take for AFPs to "graduate" out of "beta"?
   227  
   228  Things we'd like to see happen to consider AFPs well on their way:
   229  * A set of AFPs that show healthy process around describing an effort and recording decisions in a reasonable amount of time.
   230  * AFPs indexed and maintained in a structured process for easy reference.
   231  * Presubmit checks for AFPs around metadata format and markdown validity.
   232  
   233  Even so, the process can evolve. As we find new techniques we can improve our processes.
   234  
   235  ### What is the number at the beginning of the AFP name?
   236  
   237  AFPs are now prefixed with their associated tracking issue number. This gives
   238  both the AFP a unique identifier and provides an easy breadcrumb for people to
   239  find the issue where the current state of the AFP is being updated.
   240  
   241  ### My FAQ isn't answered here!
   242  
   243  The AFP process is still evolving!
   244  If something is missing or not answered here feel free to reach out to [Slack](https://join.slack.com/t/agones/shared_invite/zt-2mg1j7ddw-0QYA9IAvFFRKw51ZBK6mkQ).
   245  If you want to propose a change to the AFP process you can open a PR on [AFP-NNNN](https://github.com/googleforgames/agones/issues/new?template=feature_request.md) with your proposal.