Skip to content

Commit

Permalink
Update standard to include DR (#352)
Browse files Browse the repository at this point in the history 
Update the relevant standard to differentiate DR and Standard.

Signed-off-by: Hannes Baum <hannes.baum@cloudandheat.com>
  • Loading branch information
@cah-hbaum
cah-hbaum committed Jan 30, 2024
1 parent 9c0d816 commit 4f4431c
Showing 1 changed file with 309 additions and 0 deletions.
309 changes: 309 additions & 0 deletions Standards/scs-0001-v2-sovereign-cloud-standards.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,309 @@
---
title: Sovereign Cloud Standards
type: Procedural
status: Draft
track: Global
replaces: scs-0001-v1-sovereign-cloud-standards.md
description: |
SCS-0001 outlines the structure, requirements, and lifecycle of standards, procedural documents, and decision
records within the Sovereign Cloud Stack (SCS) community, ensuring clarity, organization, and governance in
the development and maintenance of interoperable and transparent cloud infrastructure standards.
---

## Introduction

The [Sovereign Cloud Stack (SCS)](https://scs.community) provides standards
for a range of cloud infrastructure types.
It strives for interoperable and sovereign cloud stacks
which can be deployed and used by a wide range of organizations and individuals.
Wherever feasible, transparency and openness both in respect to the inner workings of the platform
standardised by SCS, and the SCS organization itself are a paradigm we intend to live.

## Requirements

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).

In addition, "FORBIDDEN" is to be interpreted equivalent to "MUST NOT".

## Sovereign Cloud Standard documents

One of the main products of the SCS organisation are Sovereign Cloud Standard documents.

### Types of documents

#### Procedural

A procedural SCS document describes a process, a policy or a guideline to which the SCS community adheres.

#### Standard

A standard SCS document describes a technical standard for SCS compliant clouds.
Note that it may not be necessary for all clouds to implement all standards.

#### Decision Record

Sometimes during the development of the SCS standard, a complex technical decision needs to be taken,
which does not directly result in a new standard.

The SCS document format formally integrates the documentation of such decisions as documents of type `Decision Record`.

### Document format

The SCS documents are provided in GitHub flavored markdown.
Each document is assigned a unique number.
To disambiguate with other organisations using similar schemes
(such as XEPs, PEPs or IETF RFCs),
the numbers are prefixed with `SCS-`.

To allow a concept to evolve while allowing breaking changes,
each SCS document is associated with a major version number.
This major version number is a positive number
and the numbering starts at one for each document.

In order to make organisation of the SCS documents easier,
each document also has a slugified title.
The slugified title MUST NOT be changed after the acceptance of the document into the repository,
as it is part of its canonical URL.
It MUST consist only of lower-case ASCII letters, numbers and hyphens.
It MUST NOT start with a hyphen and SHOULD start with a lower-case letter.
It SHOULD NOT contain more than one subsequent hyphen.

The file name of an SCS document is formed using the following pattern:
`scs-XXXX-vN-T.md`, where
`XXXX` is replaced with the zero-padded document number,
`N` is replaced with the major version of the document, and
`T` is replaced with the slugified title.
For a document with the number 190, with a major version number 2 and a slugified title `flavor-naming`,
the resulting file name would be `scs-0190-v2-flavor-naming.md`.

The second digit in `XXXX` describes the track where the document belongs:

| Track | Number |
|--------|--------|
| Global | 0 |
| IaaS | 1 |
| KaaS | 2 |
| IAM | 3 |
| Ops | 4 |

In addition to the number, each document has the following metadata,
embedded in the markdown header.

| Field name | Requirement | Description |
|-----------------|----------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| `type` | REQUIRED | one of `Procedural`, `Standard`, or `Decision Record` |
| `status` | REQUIRED | one of `Proposal`, `Draft`, `Stable`, `Deprecated`, or `Rejected` |
| `track` | REQUIRED | one of `Global`, `IaaS`, `KaaS`, `IAM`, `Ops` |
| `obsoleted_at` | REQUIRED if `status` is `Deprecated` | ISO formatted date indicating the date after which the deprecation is in effect |
| `stabilized_at` | REQUIRED if `status` was ever `Stable` | ISO formatted date indicating the date after which the document was considered stable |
| `rejected_at` | REQUIRED if `status` is `Rejected` | ISO formatted date indicating the date on which the document was rejected |
| `replaced_by` | RECOMMENDED if `status` is `Deprecated` or `Rejected`, FORBIDDEN otherwise | List of documents which replace this document. |
| `replaces` | OPTIONAL | List of documents which this document replaces. |

### Sections

#### Standard

Each Standard document MUST have the following sections:

- An _Introduction_ providing context on the document and linking to other relevant materials.
- A _Motivation_ section which details why this document or the thing it describes is necessary.
- A _Standard_ section containing the actual standardization decision.

In addition, the following OPTIONAL sections should be considered:

- A _Terminology_ section which shortly describes terms used in the document, including possible abbreviations.
- A _Design Considerations_ section for Standard type documents,
which details other choices
which have been considered for the specific feature
but were ultimately rejected.
- An _Open Questions_ section which links to issues
detailing any open discussion points with respect to a document.
This section is RECOMMENDED during the discussion phase (pre 1.0.0)
as a "table of contents" of things to work on in that context.
- A _Related Documents_ section which references related Standards
or Decisions, both upstream and/or other SCS documents.
- A _Conformance Tests_ section that contains hints on how to validate
conformance with this spec, ideally links to conformance test cases.

#### Decision Record

Each Decision Record document MUST have the following sections:

- An _Introduction_ providing context on the document and linking to other relevant materials.
- A _Context_ section describing the issue relevant for motivating this Decision Record.
- A _Decision_ section containing the actual decision that is introduced. The section should also include
reasoning for this decision.

In addition, the following OPTIONAL sections should be considered:

- A _Terminology_ section which shortly describes terms used in the document, including possible abbreviations.
- A _Consequences_ section describing outcomes from implementing the changes described.
- A _Related Documents_ section which references related Standards
or Decisions, both upstream and/or other SCS documents.

## Process

The lifecycle of an SCS document goes through the following phases:
Proposal, Draft, Stable, Deprecated, and Rejected.

```mermaid
graph TD
A[Proposal] -->|Pull Request| B[Draft]
B -->|Pull Request| D[Stable]
B -->|Pull Request| E[Rejected]
D -->|Pull Request| F[Deprecated]
```

All decisions for phase transitions follow loose consensus,
where the group which has to form the consensus depends on the `track` of the document:

- IaaS: The team working on infrastructure-as-a-service topics
- KaaS: The team working on Kubernetes-as-a-service topics
- Ops: The team working on operations topics
- IAM: The team working on identity and access management topics
- Global: The entire SCS community

### Proposal phase

#### Proposal of a new document

To propose a new SCS document, a community participant creates a pull request on GitHub
against the [standards repository in the SovereignCloudStack organisation][scs-standards-repo].

The pull request MUST add exactly one SCS document, in the `Standards` folder.
In the proposal phase, the document number MUST be replaced with `xxxx` in the file name.
The major version MUST be 1.

For a document with a slugified title `flavor-naming`, the file name would for instance be `scs-xxxx-v1-flavor-naming.md`.

The metadata MUST indicate the intended `track` and `type` of the document, and the `status` MUST be set to `Proposal`.

Upon acceptance by the group of people identified by the `track`, a number is assigned (the next unused number)
and the proposer is asked to rename the file to replace the `xxxx` with that number.

**Note:**
Documents on the `Design Record` track MAY be proposed or accepted directly into `Stable` state,
if no further discussion is required.

Hereafter, the pull request can be merged and henceforth the document is an official SCS document in `Draft` state.

#### Proposal of a major update to a stable document

To propose major update to a Stable SCS document, a community participant creates a pull request on GitHub
against the [standards repository in the SovereignCloudStack organisation][scs-standards-repo].

The pull request MUST add exactly one SCS document, in the `Standards` folder.
The document number MUST be the same as the document it is updating,
and the major version number MUST be incremented by 1.
The slugified title MAY be changed.

It MUST refer to the old document in its `replaces` metadata.
The pull request SHOULD NOT modify the previous document; deprecation of the previous document
as well as adding the `replaced_by` metadata is a separate step,
and can only be executed once the new document is `Stable`.

For a document updating a hypothetical SCS-0390-v3 document,
the file name may be `scs-0390-v4-flavor-naming-this-time-its-serious.md`.

Other than the file naming difference, the proposal process is the same as for new documents.
In particular, the new document starts out in `Draft` state and does not
automatically become part of the normative corpus of an SCS release.

### Development phase (Draft)

In this phase, the document is developed inside the SCS community.

It should not be considered to be normative for any SCS release,
even if an SCS release happens after the acceptance of the document.

Experimental and exploratory implementations are encouraged,
however, implementors must be prepared for breaking changes.

Changes to the documents are gated through pull requests.

### Stabilized phase (Stable)

Once the document is deemed ready for production use, its `status` is changed to `Stable`.

After stabilization, changes to the document which may render existing implementations non-conformant MUST NOT be made.

If a breaking change to an existing SCS document is deemed necessary, a new document with
a new number shall be created and the old document SHOULD be deprecated.

### Deprecation phase (Deprecated)

Should a document become obsolete, it can be deprecated.

Obsoletions SHOULD be announced ahead of their execution by setting the
`deprecated_at` field to a future date and moving the `status` to `Deprecated`.
This signals current and future implementors that the subject of the document
is not considered necessary or state of the art anymore.

If one or more replacement documents for the document exists,
it MUST be listed in the `replaced_by` metadata field.

### Rejection

If a document is removed from the normative corpus of SCS standards, its status is changed to `Rejected`.

If one or more replacement documents for the document exists,
it MUST be listed in the `replaced_by` metadata field.

## Open Questions

### Stabilization criteria

When should a document be stabilized?
Should we require at least one public implementation?
Should we require a minimum experimental time?
What about non-Standard track documents?

### Breaking change criteria

When is a change breaking and cannot be applied to a Stable document?
What about previously undefined behaviour (uncovered edge case)?
What about ambiguous wording?
Do we need a separate "Errata" section?

## Design Considerations

### Versioning

An alternative to the proposed scheme for stabilization
is the use of [SemVer-like][semver] versioning.

In that case, one would have an individual version number with each document,
where a major version greater than zero indicates a stable document.
The `Stable` state would be merged with `Draft` state into an _Active_ state
and shared between the stabilized and the development phase.

The advantages of such an approach are:

- It is easy to recognize whether an SCS document has changed between two SCS releases,
just by looking at the released version number.
- It is possible to make breaking changes after stabilization by increasing the major version number.

The disadvantages of that approach are:

- It is possible to make breaking changes after stabilization.
Potentially, a hypothetical SCS-1234 document might refer to something completely different
in a hypothetical R15 release than what it meant in R5,
if there have been sufficient, gradual breaking changes to the document.

That means that for proper linking, it would be required to always include the major version number
when referring to an SCS document.

This implies having to keep all former versions around in a canonical, linkable form.
This induces non-trivial organizational and editorial overhead and raises questions around
which changes are acceptable to "archived" versions, if any.

- It would require a clone of the SemVer spec, as that spec is highly specific toward software and does not fully
(at least not in the standard-as-written) cover specifics of a standards organisation's use-cases.

## Acknowledgements

This document is heavily inspired by [XEP-0001](https://xmpp.org/extensions/xep-0001.html), as published by the XMPP Standards Foundation.

[semver]: https://semver.org/
[scs-standards-repo]: https://github.com/SovereignCloudStack/standards

0 comments on commit 4f4431c

Please sign in to comment.