diff --git a/enhancements/README.md b/enhancements/README.md new file mode 100644 index 000000000..25708a835 --- /dev/null +++ b/enhancements/README.md @@ -0,0 +1 @@ +This directory stores all of our Sail Enhancement Proposal (SEP) documents in markdown format. For more information on the process around enhancements, see [SEP1-enhancement-process.md](./SEP1-enhancement-process.md). If you want to create a SEP, be sure to check out the [SEP template](./SEP0-template.md). diff --git a/enhancements/SEP0-template.md b/enhancements/SEP0-template.md new file mode 100644 index 000000000..a57a1750a --- /dev/null +++ b/enhancements/SEP0-template.md @@ -0,0 +1,41 @@ +|Status | Authors | Created | +|---------------------------------------------------|--------------|------------| +|WIP/Proposed/Accepted/Declined/Implementation/Done | @dgn | 2024-07-09 | + +# SEP Template + +## Overview +Some short paragraphs on what the enhancement attempts to solve and why it's important. + +## Goals +Itemized list of things you want to achieve. Can be functional/nonfunctional requirements. + +## Non-goals +Itemized list of things specifically excluded from the design. Could be either to simplify the review or to avoid misunderstandings. + +## Design +This is free-form; use as many or few sub-headings as appropriate. The following are just examples, use them only if they apply to your SEP. + +### User Stories + +### API Changes + +### Architecture + +### Performance Impact + +### Backward Compatibility + +### Kubernetes vs OpenShift vs Other Distributions + +## Alternatives Considered +Other approaches that have been discussed and discarded during or before the creation of the SEP. Should include the reasons why they have not been chosen. + +## Implementation Plan +In the beginning, this should give a rough overview of the work required to implement the SEP. Later on when the SEP has been accepted, this should list the epics that have been created to track the work. + +## Test Plan +When and how can this be tested? We'll want to automate testing as much as possible, so we need to start about testability early. + +## Change History (only required when making changes after SEP has been accepted) +* 2024-07-09 Fixed a typo diff --git a/enhancements/SEP1-enhancement-process.md b/enhancements/SEP1-enhancement-process.md new file mode 100644 index 000000000..1e4bf7573 --- /dev/null +++ b/enhancements/SEP1-enhancement-process.md @@ -0,0 +1,55 @@ +|Status | Authors | Created | +|---------------------------------------------------|--------------|------------| +|WIP | @dgn | 2024-07-09 | + +# Sail Enhancement Proposal (SEP) Process + +## Overview + + +## Goals +For non-trivial (for definition see below) changes to the sail-operator, we're going to use an open design process that allows us to: +1. discuss designs and potential APIs in detail where GitHub issues might not be sufficient, +1. record important architectural decisions so we can find and reference them later on, +1. identify functional and non-functional requirements before implementation, +1. conduct our design in the open so that community members can participate and +1. use asynchronous communication throughout to minimize meeting load. + +## Non-goals +1. Overcomplicating the engineering process. Simple things should stay simple - just submit a PR to fix that bug. It's the hard things we want to make sure to get right using this process. But that doesn't mean you have to write pages of prose. Keep the SEPs short and concise, it will make reviews easier and speed up the process. + +## Design + +### Applicability +The SEP process should be used for non-trivial features or epics and any API changes. Changes without user impact will most of the time not need a SEP, but if they're big enough or result in changes to the development workflows (e.g. a rewrite of our integration testing framework) it's probably a good idea to create one. + +If your Proposal includes work that has to be done in Istio, depending on the size of the patchset it might be required to create an Istio design doc. If you do create one, make sure to link to it in the SEP. + +### Storage +Initially, SEPs will be stored in the enhancements/ directory of the sail-operator repository in Markdown format. We might migrate them to a separate repository later on. + +### Creating a SEP +Whenever somebody working on the sail-operator identifies a feature that involves a lot of code and/or API changes, they should use [the template](./SEP0-template.md) to create a SEP in WIP state for it that captures the essence of the problem and a first draft of a design that will be used as a basis for discussion. Diagrams are often helpful when discussing complex issues; if your SEP makes use of them, they should be pushed to the [diagrams subdirectory](./diagrams/). Proof-of-Concept PRs are great too - make sure to link them in the SEP. + +If possible, team up with others to create the SEP! + +### Review Process +We're using a normal GitHub review workflow. For now, every member of the team can approve these PRs and merge them. We can adjust that later if we find that it would be better to have a smaller group of people with approval rights. + +### Accepted SEP +A SEP should only be marked as accepted once all relevant sections have been filled out, especially the design, implementation and testing plan parts. + +Once a SEP is accepted, it is considered read-only. Should a change be urgently required (maybe as a result of a team discussion), there can be exceptions to this rule, though - especially if it's a small change that doesn't warrant a separate SEP. Any post-acceptance changes should include a dated (ISO format: yyyy-mm-dd) one-line summary of the changeset (can be the same as the commit message) at the bottom of the document. + +## Alternatives Considered + +* Using GDocs for storage - good for collaboration and search but hard to "lock down" a document once it has been approved. Also there's a disconnect between the code and the documents +* ad-hoc meetings and slack discussions - this is what we've done up until now but it's not community-friendly and hard to do across time zones + +## Implementation Plan + +We will start using this process ASAP. This SEP can stay in WIP state for a while though, until we're sure we have fine-tuned everything for our needs. + +## Test Plan + +N/A diff --git a/enhancements/diagrams/README.md b/enhancements/diagrams/README.md new file mode 100644 index 000000000..d71558111 --- /dev/null +++ b/enhancements/diagrams/README.md @@ -0,0 +1 @@ +Any diagrams used in the SEPs can be pushed here. Make sure to prefix them with your SEP key and add a meaningful name (e.g. `SEP0042-performance-stats.png`)