Right now, we just post design documents as comments. This can be kind of confusing - take #3008 (comment) as an example:

• This is not the first comment - rather, it's a follow-on after a lengthy discussion. I don't think that's bad per-se, and to help the situation I changed the first comment to link down to the design, but it is a bit busy.
  • We also sometimes head a different way and just open a new issue with the design and close the requesting/related issues. This has the advantage of keeping the design as the top comment.
• The use of comments for design provides no version control. In particular, again poking on the same issue, we now have discussion after the design that has already been addressed in the design - so the comment has been updated and now the discussion no longer makes sense.
• When commenting on longer designs, it's tedious to have to quote the section, vs being able to comment inline.

For these reasons and others, Kubernetes uses the KEP process. I propose a similar, lightweight version for Agones, the AFP - Agones Feature Proposals (open to better names!):

• We create a directory agones/docs/proposals in https://github.com/googleforgames/agones/tree/main/docs
• When someone wants to write a design, start with an issue outlining the problem. After that, they have two options:
  • For smaller changes, writing it in the issue is still fine.
  • For larger changes, or when asked by a maintainer because the conversation is getting unwieldy, they submit an AFP PR
• An AFP PR is as simple as a PR that adds a file in agones/docs/features. The PR should be titled AFP-00x and the file named 00x-feature-name.md.
  • Everyone can then participate on the PR, selecting text they want to comment on and having conversations there.
  • When we reach lazy consensus, a maintainer can approve and submit.
  • Every AFP OR should be tied back to an issue

Thoughts?