Support Policy Updates (#2536)

* Support Policy Updates
---------

Co-authored-by: James Hodgkinson <james@terminaloutcomes.com>

SECURITY.md

@@ -4,11 +4,6 @@ Thanks for taking the time to engage with the project! We believe in the concept
 [coordinated disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure) and
 currently expect a 60 day grace period for resolution of any outstanding issues.
 
-## Supported Versions
-
-As Kanidm is in early Alpha and under heavy development, only the most recent release and current
-HEAD of the main branch will be supported.
-
 ## Reporting a Vulnerability
 
 Please log a security-template issue on Github and directly contact one of the core team members via

book/src/integrations/oauth2.md

@@ -343,7 +343,8 @@ In the virtual host, to handle OIDC redirect, a special location _must_ be defin
 </Location>
 ```
 
-In the virtual host, to protect a location/directory [see wiki](https://github.com/OpenIDC/mod_auth_openidc/wiki/Authorization):
+In the virtual host, to protect a location/directory
+[see wiki](https://github.com/OpenIDC/mod_auth_openidc/wiki/Authorization):
 
 ```apache
 <Directory /foo>

project_docs/RELEASE_AND_SUPPORT.md

@@ -1,4 +1,22 @@
-## Release Schedule
+# Kanidm - Support and Release Processes
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kanidm/kanidm/master/artwork/logo-small.png" width="20%" height="auto" />
+</p>
+
+# Introduction
+
+This document describes the Kanidm project teams support and release version processes.
+
+While we have made every effort to ensure this document is complete, in the event that something is
+missing or if you have a question, please
+[open a discussion](https://github.com/kanidm/kanidm/discussions).
+
+The version of this document found
+[on the project page](https://github.com/kanidm/kanidm/blob/master/project_docs/RELEASE_AND_SUPPORT.md)
+is considered authoritive and applies to all versions.
+
+## Release Schedule and Versioning
 
 Kanidm is released on a 3 month (quarterly) basis.
 
@@ -7,45 +25,96 @@ Kanidm is released on a 3 month (quarterly) basis.
 - August 1st
 - November 1st
 
-Releases will be tagged and branched in git.
+Versions follow semver using `major.minor.patch` with an optional `-tag`.
 
-1.2.0 will be released as the first supported version once the project believes the project is in a
+- development branch: `X.Y.Z-dev`
-maintainable longterm state, without requiring backward breaking changes. There is no current
+- pre-release branch: `X.Y.Z-pre`
-estimated date for 1.2.0.
+- stable branch: `X.Y.Z`
+
+Release branches will be created and tagged 7 days prior to a release. The version will be set to
+the pre-release version.
+
+```
+  /- tag 1.2.0-dev
+  |          tag 1.3.0-dev
+  v          v
+--o ... --o--o--o--o ...  <- branch master
+           \
+            \-o--o--o--o--o--o--o  <- branch 1.2.0
+              ^        ^  ^
+              |        |   tag v1.2.1
+              |        \- tag v1.2.0
+              \- tag v1.2.0-pre
+```
+
+The first stable release is version 1.2.0. All releases prior are release candidate, beta or alpha
+builds and will no longer be supported as of the release of 1.2.0.
 
 ## Support
 
-Releases during alpha will receive limited fixes once released. Specifically we will resolve:
+Stable releases will be supported for 4 months after their release date. This allows a 1 month
+support overlap between N and N+1 versions.
 
-- Moderate security issues and above
+Stable releases will have the following support provided during their support window.
-- Flaws leading to dataloss or corruption
-- Other quality fixes at the discrestion of the project team
 
-These will be backported to the latest stable branch only.
+- Security fixes
+- Fixes for flaws leading to dataloss or corruption
+- Fixes that impact the ability to upgrade
+- Other quality fixes at the discretion of the project team
 
-## API stability
+### Replication
 
-There are a number of "surfaces" that can be considered as "API" in Kanidm.
+All nodes must be the same version. A topology may contain up to a maximum of 2 nodes.
+
+### Upgrade Policy
+
+Upgrades are supported from 1 release before the current stable release.
+
+### Tool Versions
+
+Command line tools (`kanidm`) and sync connectors (`kanidm-ipa-sync`, `kanidm-ldap-sync`) must be
+matched versions with the server that they communicate with.
+
+### API stability
+
+Kanidm has a number of APIs with different stability guarantees. APIs that are stable will only
+recieve breaking changes in the case of an ethics, security or potential data corruption issue.
+
+Stable APIs are:
+
+- LDAP protocol operations
+- JSON HTTP end points which use elements from
+  [`proto/src/v1.rs`](https://github.com/kanidm/kanidm/blob/master/proto/src/v1.rs)
+- SCIM operations from
+  [`proto/src/scim_v1.rs`](https://github.com/kanidm/kanidm/blob/master/proto/src/scim_v1.rs)
+
+All other APIs and interactions are not considered stable. Changes will be minimised if possible.
+This includes but is not limited to:
 
-- JSON HTTP end points of kanidmd
 - unix domain socket API of `kanidm_unixd` resolver
-- LDAP interface of kanidm
+- unix admin domain socket for `kanidmd` server
-- CLI interface of kanidm admin command
+- web user interface design and operations
-- Many other interaction surfaces
+- entry schema
+- CLI interface of any command provided by kanidm unless otherwise noted above
+- JSON HTTP end points which use elements from
+  [`proto/src/internal.rs`](https://github.com/kanidm/kanidm/blob/master/proto/src/internal.rs)
 
-During the Alpha, there is no guarantee that _any_ of these APIs named here or not named will remain
+### Deprecation Policy
-stable. Only elements from "the same release" are guaranteed to work with each other.
 
-Once an official release is made, only the JSON API and LDAP interface will be declared stable.
+Features or APIs may be removed with 1 release versions notice. Deprecations will be announced in
+[the Release Notes](https://github.com/kanidm/kanidm/blob/master/RELEASE_NOTES.md)
 
-The unix domain socket API is internal and will never be "stable".
+### Python module
-
-The CLI is _not_ an API and can change with the interest of human interaction during any release.
-
-## Python module
 
 The python module will typically trail changes in functionality of the core Rust code, and will be
 developed as we it for our own needs - please feel free to add functionality or improvements, or
 [ask for them in a Github issue](http://github.com/kanidm/kanidm/issues/new/choose)!
 
 All code changes will include full type-casting wherever possible.
+
+### Project Discretion
+
+In the event of an unforseen or extraordinary situation, the project team may make decisions
+contradictory to this document at their discretion. In these situation, the project team will make
+every effort to communicate the reason for the decision and will attempt to minimise disruption to
+users.

project_docs/RELEASE_CHECKLIST.md

@@ -9,14 +9,15 @@ cargo install cargo-udeps
 cargo install wasm-bindgen-cli
 ```
 
-## Check List
+## Pre Release Check List
 
 ### Start a release
 
-- [ ] git checkout -b YYYYMMDD-release
+- [ ] git checkout -b YYYYMMDD-pre-release
 
 ### Cargo Tasks
 
+- [ ] Update MSRV if applicable
 - [ ] RUSTC\_BOOTSTRAP=1 cargo udeps
 - [ ] cargo outdated -R
 - [ ] cargo audit
@@ -24,20 +25,18 @@ cargo install wasm-bindgen-cli
 
 ### Code Changes
 
-- [ ] upgrade crypto policy values if requires
+- [ ] upgrade crypto policy values if required
 - [ ] bump index version in constants
 - [ ] check for breaking db entry changes.
 
 ### Administration
 
-- [ ] update version to remove dev tag in ./Cargo.toml
-- [ ] update version to remove dev tag in ./Makefile
 - [ ] cargo test
 - [ ] build wasm components with release profile
 - [ ] Update `RELEASE_NOTES.md`
 - [ ] Update `README.md`
 - [ ] git commit
-- [ ] git push origin YYYYMMDD-release
+- [ ] git push origin YYYYMMDD-pre-release
 - [ ] Merge PR
 
 ### Git Management
@@ -45,7 +44,10 @@ cargo install wasm-bindgen-cli
 - [ ] git checkout master
 - [ ] git pull
 - [ ] git checkout -b 1.1.x (Note no v to prevent ref conflict)
-- [ ] git tag v1.1.x
+- [ ] update version to set pre tag in ./Cargo.toml
+- [ ] update version to set pre tag in ./Makefile
+- [ ] git commit
+- [ ] git tag v1.1.x-pre
 
 - [ ] Final inspect of the branch
 
@@ -53,9 +55,34 @@ cargo install wasm-bindgen-cli
 - [ ] git push origin 1.1.x --tags
 
 - [ ] github -> Ensure release branch is protected
+
+### Follow up
+
+- [ ] git checkout master
+- [ ] git pull
+- [ ] git checkout -b YYYYMMDD-dev-version
+- [ ] update version to +1 and add dev tag in ./Cargo.toml
+- [ ] update version to +1 and add dev tag in ./Makefile
+
+## Final Release Check List
+
+### Git Management
+
+- [ ] git checkout 1.1.x
+- [ ] git pull origin 1.1.x
+
+- [ ] update version to remove pre tag in ./Cargo.toml
+- [ ] update version to remove pre tag in ./Makefile
+- [ ] git tag v1.1.x
+- [ ] git push origin 1.1.x --tags
+
 - [ ] github -> create new release based on tag (not branch) - use tag because then tools will get
       the tag + patches we apply.
 
+### Community
+
+- [ ] Publish release announcement
+
 ### Cargo publish
 
 - [ ] publish `kanidm_proto`
@@ -77,11 +104,3 @@ cargo install wasm-bindgen-cli
 ### Distro
 
 - [ ] vendor and release to build.opensuse.org
-
-### Follow up
-
-- [ ] git checkout master
-- [ ] git pull
-- [ ] git checkout -b YYYYMMDD-dev-version
-- [ ] update version to +1 and add dev tag in ./Cargo.toml
-- [ ] update version to +1 and add dev tag in ./Makefile