This directory contains all documents informing Crossplane's design. Crossplane designs must transition through up to three of the following phases:
- Proposals. A proposal is simply a Github issue against this reposistory with
the
proposallabel. Proposals need not be more than two to three paragraphs. - One-pagers. A One-pager is a brief document pitching an idea for further experimentation. One-pagers, as the name suggests, are usually around one page long. They provide just enough context to achieve buy-in from Crossplane maintainers.
- Design documents. A design document is a longer, more detailed design. Design documents should typically be preceeded by a one-pager and/or a good amount of research and experimentation.
All designs must start as a proposal. In some simple cases this proposal alone
is sufficient to move forward with a design. As the complexity or controversy of
the proposed design increases a one-pager and/or design document may be
required. Please name your documents appropriately when committing to this
directory, i.e. one-pager-my-cool-design.md or design-doc-my-cool-design.md.
All documents committed to this directory must include the following header:
# Document Title
* Owner: Some Person (@GithubUsername)
* Reviewers: Crossplane Maintainers
* Status: Accepted, revision 1.0The document owner is the person responsible for stewarding its lifecycle. The owner will typically be the original document author, though ownership may be handed over to another individual over time. The owner may choose to include their email address, but doing so is not mandatory.
The document reviewers are a small, targeted audience. Feedback is always welcome from any member of the Crossplane community, but feedback from the elected reviewers carries extra weight.
The document status reflects the lifecycle of the design. Designs may be committed to master at any stage in their lifecycle as long as the status is indicated clearly. Use one of the following statuses:
- Speculative designs explore an idea without yet explicitly proposing a change be made. Typically only one-pagers will be speculative.
- Draft designs strive toward acceptance. Designs may exist in draft for some time as we experiment and learn, but their ultimate goal is to become an accepted design.
- Accepted designs reflect the current or impending state of the codebase. Documents may transition from draft to accepted only after receiving approval from a majority of the document's elected reviewers. Once a document reaches accepted status it should also include a major.minor style abbreviated semantic version number reflecting substantial updates to the design over time.
- Defunct designs are kept for historical reasons, but do not reflect the current or impending state of the codebase either because they were never accepted or because they were accepted but are no longer reflective of the state of the codebase.