diff --git a/.github/ISSUE_TEMPLATE/agones_feature_proposal.md b/.github/ISSUE_TEMPLATE/agones_feature_proposal.md new file mode 100644 index 0000000000..e504bc0f3e --- /dev/null +++ b/.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] - ' +labels: kind/feature, kind/operations, kind/afp +assignees: '' + +--- + +- One-line feature description (can be used as a release note): +- Agones Feature Proposal: +- Discussion Link: +- 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): + + + +_Please keep this description up to date. This will help the Maintainer to track the evolution of the feature efficiently._ diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index d681cbf060..0000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: kind/feature -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.yamllint b/.yamllint index 3e14c20ab9..2a378735be 100644 --- a/.yamllint +++ b/.yamllint @@ -49,3 +49,4 @@ ignore: - /site/vendor/ - /tmp/ - /vendor/ + - /docs/proposals diff --git a/docs/proposals/0000-afp-process/README.md b/docs/proposals/0000-afp-process/README.md new file mode 100644 index 0000000000..6ea94600de --- /dev/null +++ b/docs/proposals/0000-afp-process/README.md @@ -0,0 +1,309 @@ +# Agones Feature Proposal Process + +## Table of Contents + + +- [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) + + +## 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. + + +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. + + +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 + +- diff --git a/docs/proposals/0000-afp-process/afp.yaml b/docs/proposals/0000-afp-process/afp.yaml new file mode 100644 index 0000000000..b1effba0b9 --- /dev/null +++ b/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 diff --git a/docs/proposals/NNNN-afp-template/README.md b/docs/proposals/NNNN-afp-template/README.md new file mode 100644 index 0000000000..e23c3fa79e --- /dev/null +++ b/docs/proposals/NNNN-afp-template/README.md @@ -0,0 +1,640 @@ + +# AFP-NNNN: Your short, descriptive title + + + + + + +- [Release Signoff Checklist](#release-signoff-checklist) +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) +- [Proposal](#proposal) + - [User Stories (Optional)](#user-stories-optional) + - [Story 1](#story-1) + - [Story 2](#story-2) + - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional) + - [Risks and Mitigations](#risks-and-mitigations) +- [Design Details](#design-details) + - [Test Plan](#test-plan) + - [Prerequisite testing updates](#prerequisite-testing-updates) + - [Unit tests](#unit-tests) + - [e2e tests](#e2e-tests) + - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) +- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire) + - [Feature Enablement and Rollback](#feature-enablement-and-rollback) + - [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning) + - [Monitoring Requirements](#monitoring-requirements) + - [Dependencies](#dependencies) + - [Scalability](#scalability) + - [Troubleshooting](#troubleshooting) +- [Implementation History](#implementation-history) +- [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) +- [Infrastructure Needed (Optional)](#infrastructure-needed-optional) + + +## Release Signoff Checklist + + + +Items marked with (R) are required *prior to targeting to a milestone / release*. + +- [ ] (R) Feature issue in release milestone, which links to AFP dir in [agones/proposals] (not the initial AFP PR) +- [ ] (R) AFP approvers have approved the AFP status as `implementable` +- [ ] (R) Design details are appropriately documented +- [ ] (R) Test plan is in place, considering input from the Agones Architecture and Agones Testing (including test refactors) + - [ ] (R) End-to-End (E2E) Tests must cover all key Agones API operations (e.g., GameServer, GameServerSet, Fleet, FleetAllocation, and Controller). +- [ ] (R) Implementation review completed +- [ ] (R) Implementation review approved +- [ ] "Implementation History" section is up-to-date for milestone +- [ ] User-facing documentation has been created in [agones/site], for publication to [agones.dev] +- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/community meetings, relevant PRs/issues, release notes + + + +[agones.dev]: https://agones.dev +[agones/proposals]: https://github.com/googleforgames/agones/tree/main/docs/proposals +[googleforgames/agones]: https://github.com/googleforgames/agones +[agones/site]: https://github.com/googleforgames/agones/tree/main/site + +## Summary + + + +## Motivation + + + +### Goals + + + +### Non-Goals + + + +## Proposal + + + +### User Stories (Optional) + + + +#### Story 1 + +#### Story 2 + +### Notes/Constraints/Caveats (Optional) + + + +### Risks and Mitigations + + + +## Design Details + + + +### Test Plan + + + +[ ] I/we understand the owners of the involved components may require updates to +existing tests to make this code solid enough prior to committing the changes necessary +to implement this proposal. + +##### Prerequisite testing updates + + + +##### Unit tests + + + +- ``: `` - `` + +##### e2e tests + + + +- : + +### Upgrade / Downgrade Strategy + + + +## Production Readiness Review Questionnaire + + + +### Feature Enablement and Rollback + + + +###### How can this feature be enabled / disabled in a live cluster? + + + +- [ ] Feature gate (also fill in values in `afp.yaml`) + - Feature gate name: + - Components depending on the feature gate: +- [ ] Other + - Describe the mechanism: + - Will enabling / disabling the feature require downtime of the control + plane? + - Will enabling / disabling the feature require downtime or reprovisioning + of a node? + +###### Does enabling the feature change any default behavior? + + + +###### Can the feature be disabled once it has been enabled (i.e. can we roll back the enablement)? + + + +###### What happens if we reenable the feature if it was previously rolled back? + +### Rollout, Upgrade and Rollback Planning + + + +###### How can a rollout or rollback fail? Can it impact already running workloads? + + + +###### What specific metrics should inform a rollback? + + + +###### Were upgrade and rollback tested? Was the upgrade->downgrade->upgrade path tested? + + + +###### Is the rollout accompanied by any deprecations and/or removals of features, APIs, fields of API types, flags, etc.? + + + +### Monitoring Requirements + + + +###### How can an operator determine if the feature is in use by workloads? + + + +###### How can someone using this feature know that it is working for their instance? + + + +- [ ] Events + - Event Reason: +- [ ] API .status + - Condition name: + - Other field: +- [ ] Other (treat as last resort) + - Details: + +###### What are the reasonable SLOs (Service Level Objectives) for the proposal? + + + +###### What are the SLIs (Service Level Indicators) an operator can use to determine the health of the service? + + + +- [ ] Metrics + - Metric name: + - [Optional] Aggregation method: + - Components exposing the metric: +- [ ] Other (treat as last resort) + - Details: + +###### Are there any missing metrics that would be useful to have to improve observability of this feature? + + + +### Dependencies + + + +###### Does this feature depend on any specific services running in the cluster? + + + +### Scalability + + + +###### Will enabling / using this feature result in any new API calls? + + + +###### Will enabling / using this feature result in introducing new API types? + + + +###### Will enabling / using this feature result in any new calls to the cloud provider? + + + +###### Will enabling / using this feature result in increasing size or count of the existing API objects? + + + +###### Will enabling / using this feature result in non-negligible increase of resource usage (CPU, RAM, disk, IO, ...) in any components? + + + +### Troubleshooting + + + +###### How does this feature react if the Game server and/or fleet is unavailable? + +###### What are other known failure modes? + + + +###### What steps should be taken if Scalability/Performance are not being met to determine the problem? + +## Implementation History + + + +## Drawbacks + + + +## Alternatives + + + +## Infrastructure Needed (Optional) + + diff --git a/docs/proposals/NNNN-afp-template/afp.yaml b/docs/proposals/NNNN-afp-template/afp.yaml new file mode 100644 index 0000000000..efd9f1d8f1 --- /dev/null +++ b/docs/proposals/NNNN-afp-template/afp.yaml @@ -0,0 +1,46 @@ +--- +title: AFP Template +afp-number: NNNN +authors: + - "@jane.doe" +status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced +creation-date: yyyy-mm-dd +reviewers: + - TBD + - "@alice.doe" +approvers: + - TBD + - "@oscar.doe" + +see-also: + - "/docs/proposals/1234-we-heard-you-like-afps" + - "/docs/proposals/2345-everyone-gets-a-afp" +replaces: + - "/docs/proposals/3456-replaced-afp" + +# The target maturity stage in the current dev cycle for this AFP. +stage: alpha|beta|stable + +# The most recent milestone for which work toward delivery of this AFP has been +# done. This can be the current (upcoming) milestone, if it is being actively +# worked on. +latest-milestone: "v1.46.0" + +# The milestone at which this feature was, or is targeted to be, at each stage. +milestone: + alpha: "v1.46.0" + beta: "v1.47.0" + stable: "v1.48.0" + +# The following PRR answers are required at next release +# List the feature gate name and the components for which it must be enabled +feature-gates: + - name: MyFeature + components: + - CountsAndLists + - GKEAutopilotExtendedDurationPods +disable-supported: true + +# The following PRR answers are required at beta release +metrics: + - my_feature_metric diff --git a/docs/proposals/README.md b/docs/proposals/README.md new file mode 100644 index 0000000000..16da703c0a --- /dev/null +++ b/docs/proposals/README.md @@ -0,0 +1,64 @@ +# Agones Feature Proposals (AFPs) + +A Agones Feature Proposal (AFP) is a way to propose, communicate and coordinate on new efforts for the Agones project. +You can read the full details of the project in [AFP-0000](0000-afp-process/README.md). + +## Quick start for the AFP process + +1. Write a proposal outlining the new feature or improvement you wish to introduce to Agones. Submit your proposal by creating an issue in the Agones GitHub repository, following the [AFP template](NNNN-afp-template/README.md) Make sure that others think the work is worth taking up and will help review the AFP and any code changes required. +2. Follow the process outlined in the [AFP template](NNNN-afp-template/README.md) + +## FAQs + +### Do I have to use the AFP process? + +More or less, yes. + +Having a rich set of AFPs in one place will make it easier for people to track +what is going in the community and find a structured historical record. + +AFPs are required for most non-trivial changes. Specifically: +* Anything that may be controversial +* Most new features (except the very smallest) +* Major changes to existing features +* Changes that are wide ranging or impact most of the project (these changes + are usually coordinated through the relevant maintainers) + +Beyond these, it is up to the team to decide when they want to use the AFP +process. It should be light-weight enough that AFPs are the default position. + + +### Why would I want to use the AFP process? + +Our aim with AFPs is to clearly communicate new efforts to the Agones contributor community. +As such, we want to build a well curated set of clear proposals in a common format with useful metadata. + +Benefits to AFP users (in the limit): +* Exposure on a agones blessed web site that is findable via web search engines. +* Cross indexing of AFPs so that users can find connections and the current status of any AFP. +* A clear process with approvers and reviewers for making decisions. + This will lead to more structured decisions that stick as there is a discoverable record around the decisions. + +We are inspired by K8S KEPs, Python PEPs and Rust RFCs. +See [AFP-0000](0000-afp-process/README.md) for more details. + +### What will it take for AFPs to "graduate" out of "beta"? + +Things we'd like to see happen to consider AFPs well on their way: +* A set of AFPs that show healthy process around describing an effort and recording decisions in a reasonable amount of time. +* AFPs exposed on a searchable and indexable web site. +* Presubmit checks for AFPs around metadata format and markdown validity. + +Even so, the process can evolve. As we find new techniques we can improve our processes. + +### What is the number at the beginning of the AFP name? + +AFPs are now prefixed with their associated tracking issue number. This gives +both the AFP a unique identifier and provides an easy breadcrumb for people to +find the issue where the current state of the AFP is being updated. + +### My FAQ isn't answered here! + +The AFP process is still evolving! +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). +If you want to propose a change to the AFP process you can open a PR on [AFP-0000](0000-afp-process/README.md) with your proposal. diff --git a/site/content/en/docs/Contribute/_index.md b/site/content/en/docs/Contribute/_index.md index 0ea9faef53..d1869bd1f2 100644 --- a/site/content/en/docs/Contribute/_index.md +++ b/site/content/en/docs/Contribute/_index.md @@ -1,69 +1,7 @@ --- -title: "Documentation Editing and Contribution" +title: "Contribute" linkTitle: "Contribute" weight: 1000 description: > - How to contribute to the docs + Contribute to the Platform --- - -## Writing Documentation - -We welcome contributions to documentation! - -## Running the site - -If you clone the repository and run `make site-server` from the `build` directory, this will run the live hugo server, -running as a showing the next version's content and upcoming `publishedDate`'d content as well. This is likely to be -the next releases' version of the website. - -To show the current website's view, run it as `make site-server ENV=RELEASE_VERSION={{< release-version >}} ARGS=` - -## Platform - -This site and documentation is built with a combination of Hugo, static site generator, -with the Docsy theme for open source documentation. - -- [Hugo Documentation](https://gohugo.io/documentation/) -- [Docsy Guide](https://github.com/google/docsy) -- [Link Checker](https://github.com/wjdp/htmltest) - -## Documentation for upcoming features - -Since we may want to update the existing documentation for a given release, when writing documentation, -you will likely want to make sure it doesn't get published until the next release. - -There are two approaches for hiding documentation for upcoming features, such that it only gets published when the -version is incremented on the release: - -### At the Page Level - -Use `publishDate` and `expiryDate` in [Hugo Front Matter](https://gohugo.io/content-management/front-matter/) to control -when the page is displayed (or hidden). You can look at the [Release Calendar](https://github.com/googleforgames/agones/blob/main/docs/governance/release_process.md#release-calendar) -to align it with the next release -candidate release date - or whichever release is most relevant. - -### Within a Page - -We have a `feature` shortcode that can be used to show, or hide sections of pages based on the current semantic version -(set in config.toml, and overwritable by env variable). - -For example, to show a section only from 1.24.0 forwards: - -```markdown -{{%/* feature publishVersion="1.24.0" */%}} - This is my special content that should only display >= 1.24.0 -{{%/* /feature */%}} -``` - -or to hide a section from 1.24.0 onward: - -```markdown -{{%/* feature expiryVersion="1.24.0" */%}} - This is my special content that will be hidden >= 1.24.0 -{{%/* /feature */%}} -``` - -## Regenerate Diagrams - -To regenerate the [PlantUML](http://plantuml.com/) or [Dot](https://www.graphviz.org/doc/info/lang.html) diagrams, -delete the .png version of the file in question from `/site/static/diagrams/`, and run `make site-images`. \ No newline at end of file diff --git a/site/content/en/docs/Contribute/agones-feature-proposal.md b/site/content/en/docs/Contribute/agones-feature-proposal.md new file mode 100644 index 0000000000..5bae730436 --- /dev/null +++ b/site/content/en/docs/Contribute/agones-feature-proposal.md @@ -0,0 +1,85 @@ +--- +title: "Agones Feature Proposal (AFP)" +linkTitle: "Agones Feature Proposal" +weight: 1000 +description: > + Suggest a new feature or enhancement for the Agones project. +--- + +## Overview of the Agones Feature Proposal (AFP) Process + +The **Agones Feature Proposal (AFP)** process provides a standardized way to propose, discuss, and track new features, enhancements, or architectural changes within the Agones project. This process is intended to ensure clarity, transparency, and collaborative decision-making, allowing stakeholders to effectively contribute to and communicate about important changes in the project. + +### Key Objectives of the AFP Process + +- **Standardized Proposals**: Offers a common structure for proposing changes, ensuring that the motivation for a feature, its implementation, and its impact are clearly defined. +- **Cross-Team Communication**: Facilitates collaboration across different teams within the Agones community, ensuring that all relevant stakeholders are informed and involved in the decision-making process. +- **Roadmap Integration**: Supports the creation of a user-facing development roadmap that outlines upcoming features and changes. +- **Feature Tracking**: Allows features and major changes to be tracked across one or more releases, providing a historical record of decisions and progress. + +### AFP Structure + +Each AFP consists of several key sections that are defined incrementally as the feature progresses. These sections typically include: + +- **Motivation**: The reasoning behind the proposed change, including its expected impact on users and developers. +- **Reference-Level Explanation**: Detailed technical information about how the feature will be implemented and integrated. +- **Stewardship**: Clarification of the roles and responsibilities of key participants in the AFP process. +- **Drawbacks**: Acknowledgment of potential issues or downsides of the proposal. +- **Alternatives**: Discussion of alternative approaches to achieving the desired outcome. +- **Unresolved Questions**: A place to document any open questions or issues that need further clarification. + +### AFP Workflow and States + +The AFP process follows a series of stages to ensure that the proposal is well-defined, reviewed, and implemented in a structured manner. These stages include: + +1. **Provisional**: The AFP is actively being discussed and defined. +2. **Implementable**: The AFP has been reviewed and approved for implementation. +3. **Implemented**: The feature has been implemented and is no longer actively changing. +4. **Deferred**: The AFP is proposed but not actively worked on. +5. **Rejected**: The AFP is no longer considered viable. +6. **Withdrawn**: The authors have decided to withdraw the AFP. +7. **Replaced**: The AFP has been replaced by a new AFP. + +### How to Submit an AFP + +To submit a new AFP, follow the instructions provided in the official AFP template. This template outlines the required sections and metadata, such as the title, authors, reviewers, and approval statuses. AFPs are stored in the project's **docs/proposals** directory, with filenames formatted as `NNNN-my-title.md`. The document undergoes iterative updates, with changes tracked via version control. + +### Why AFPs Are Important + +The AFP process helps reduce **tribal knowledge** within the community by creating a centralized, transparent way to communicate significant changes. It encourages comprehensive discussions and allows for the smooth transition of features from initial idea to production. + +It is particularly beneficial for tracking: + +- **Large Features**: Features that impact a wide range of users or developers. +- **Major Refactorings**: Significant changes to the architecture that require widespread consensus. +- **Cross-Team Initiatives**: Efforts that involve multiple stakeholders and require coordination across teams. + +### How AFPs Benefit the Agones Project + +- **Improved Communication**: Provides a clear, centralized mechanism for proposing and tracking changes. +- **Better Decision-Making**: Ensures that all stakeholders, including maintainers, contributors, and users, are informed and involved in the decision-making process. +- **Long-Term Roadmap Clarity**: Helps create a roadmap for future releases, aligning community expectations and improving planning for feature adoption. + +### Learn More About AFPs + +To get started with contributing to the AFP process, check out the following resources: + +- **[AFP Template](#)**: A detailed template for creating an AFP. +- **[AFP Metadata](#)**: Information on the metadata required for each AFP. +- **[How to Propose a Feature](https://github.com/googleforgames/agones/issues/new/choose)**: Step-by-step instructions on how to submit a new AFP. + +### Examples of AFPs + +Here are some example AFPs that have been proposed or implemented in Agones: + +- **[123-AFP: Example Feature](#)**: Description of a feature proposal. +- **[124-AFP: Example Architecture Change](#)**: Description of a major architectural change proposal. + +### How to Get Involved + +We welcome contributions from all members of the Agones community! If you're interested in proposing a new feature or contributing to the ongoing development of Agones, you can start by submitting an AFP or reviewing and providing feedback on existing proposals. + +--- + +For further information or assistance, please reach out to the Agones maintainers via our [Agones Community Hub](https://agones.dev/site/community/). + diff --git a/site/content/en/docs/Contribute/documentation-editing-contribution.md b/site/content/en/docs/Contribute/documentation-editing-contribution.md new file mode 100644 index 0000000000..7868f4ee48 --- /dev/null +++ b/site/content/en/docs/Contribute/documentation-editing-contribution.md @@ -0,0 +1,69 @@ +--- +title: "Documentation Editing and Contribution" +linkTitle: "Documentation Editing and Contribution" +weight: 1000 +description: > + How to contribute to the docs +--- + +## Writing Documentation + +We welcome contributions to documentation! + +## Running the site + +If you clone the repository and run `make site-server` from the `build` directory, this will run the live hugo server, +running as a showing the next version's content and upcoming `publishedDate`'d content as well. This is likely to be +the next releases' version of the website. + +To show the current website's view, run it as `make site-server ENV=RELEASE_VERSION={{< release-version >}} ARGS=` + +## Platform + +This site and documentation is built with a combination of Hugo, static site generator, +with the Docsy theme for open source documentation. + +- [Hugo Documentation](https://gohugo.io/documentation/) +- [Docsy Guide](https://github.com/google/docsy) +- [Link Checker](https://github.com/wjdp/htmltest) + +## Documentation for upcoming features + +Since we may want to update the existing documentation for a given release, when writing documentation, +you will likely want to make sure it doesn't get published until the next release. + +There are two approaches for hiding documentation for upcoming features, such that it only gets published when the +version is incremented on the release: + +### At the Page Level + +Use `publishDate` and `expiryDate` in [Hugo Front Matter](https://gohugo.io/content-management/front-matter/) to control +when the page is displayed (or hidden). You can look at the [Release Calendar](https://github.com/googleforgames/agones/blob/main/docs/governance/release_process.md#release-calendar) +to align it with the next release +candidate release date - or whichever release is most relevant. + +### Within a Page + +We have a `feature` shortcode that can be used to show, or hide sections of pages based on the current semantic version +(set in config.toml, and overwritable by env variable). + +For example, to show a section only from 1.24.0 forwards: + +```markdown +{{%/* feature publishVersion="1.24.0" */%}} + This is my special content that should only display >= 1.24.0 +{{%/* /feature */%}} +``` + +or to hide a section from 1.24.0 onward: + +```markdown +{{%/* feature expiryVersion="1.24.0" */%}} + This is my special content that will be hidden >= 1.24.0 +{{%/* /feature */%}} +``` + +## Regenerate Diagrams + +To regenerate the [PlantUML](http://plantuml.com/) or [Dot](https://www.graphviz.org/doc/info/lang.html) diagrams, +delete the .png version of the file in question from `/site/static/diagrams/`, and run `make site-images`. \ No newline at end of file