From ea5ff6814ce40f9dff0baad36a1a9ca8cd0f4464 Mon Sep 17 00:00:00 2001 From: Firstyear Date: Sun, 18 Feb 2024 10:44:11 +1000 Subject: [PATCH] Support Policy Updates (#2536) * Support Policy Updates --------- Co-authored-by: James Hodgkinson --- SECURITY.md | 5 -- book/src/integrations/oauth2.md | 3 +- project_docs/RELEASE_AND_SUPPORT.md | 117 ++++++++++++++++++++++------ project_docs/RELEASE_CHECKLIST.md | 49 ++++++++---- 4 files changed, 129 insertions(+), 45 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index b0fbeba7f..ab1b0319c 100644 --- a/SECURITY.md +++ b/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 diff --git a/book/src/integrations/oauth2.md b/book/src/integrations/oauth2.md index da8207abc..afdfd58fc 100644 --- a/book/src/integrations/oauth2.md +++ b/book/src/integrations/oauth2.md @@ -343,7 +343,8 @@ In the virtual host, to handle OIDC redirect, a special location _must_ be defin ``` -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 diff --git a/project_docs/RELEASE_AND_SUPPORT.md b/project_docs/RELEASE_AND_SUPPORT.md index 986138593..39a032ca4 100644 --- a/project_docs/RELEASE_AND_SUPPORT.md +++ b/project_docs/RELEASE_AND_SUPPORT.md @@ -1,4 +1,22 @@ -## Release Schedule +# Kanidm - Support and Release Processes + +

+ +

+ +# 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 -maintainable longterm state, without requiring backward breaking changes. There is no current -estimated date for 1.2.0. +- development branch: `X.Y.Z-dev` +- pre-release branch: `X.Y.Z-pre` +- 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 -- Flaws leading to dataloss or corruption -- Other quality fixes at the discrestion of the project team +Stable releases will have the following support provided during their support window. -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 -- CLI interface of kanidm admin command -- Many other interaction surfaces +- unix admin domain socket for `kanidmd` server +- web user interface design and operations +- 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 -stable. Only elements from "the same release" are guaranteed to work with each other. +### Deprecation Policy -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". - -The CLI is _not_ an API and can change with the interest of human interaction during any release. - -## Python module +### 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. diff --git a/project_docs/RELEASE_CHECKLIST.md b/project_docs/RELEASE_CHECKLIST.md index 0da657fa7..3e363db36 100644 --- a/project_docs/RELEASE_CHECKLIST.md +++ b/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