Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Automated merge
Browse files Browse the repository at this point in the history
* upstream/main:
  Add enhancements/ directory (istio-ecosystem#191)
openshift-service-mesh-bot committed Jul 12, 2024
2 parents d1063c4 + eda1145 commit 0ce8f8c
Showing 4 changed files with 98 additions and 0 deletions.
1 change: 1 addition & 0 deletions enhancements/README.md
Original file line number Diff line number Diff line change
@@ -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).
41 changes: 41 additions & 0 deletions enhancements/SEP0-template.md
Original file line number Diff line number Diff line change
@@ -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
55 changes: 55 additions & 0 deletions enhancements/SEP1-enhancement-process.md
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions enhancements/diagrams/README.md
Original file line number Diff line number Diff line change
@@ -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`)

0 comments on commit 0ce8f8c

Please sign in to comment.