From 66cf429acd978e7c879daa3b7ae1890a00ecd452 Mon Sep 17 00:00:00 2001 From: 6543 <6543@obermui.de> Date: Mon, 16 Feb 2026 21:25:01 +0100 Subject: [PATCH] Add deprecation policy (#6068) Co-authored-by: Robert Kaussow --- docs/docs/92-development/40-deprecations.md | 43 +++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/docs/92-development/40-deprecations.md diff --git a/docs/docs/92-development/40-deprecations.md b/docs/docs/92-development/40-deprecations.md new file mode 100644 index 000000000..f19f17c8e --- /dev/null +++ b/docs/docs/92-development/40-deprecations.md @@ -0,0 +1,43 @@ +# Deprecation Policy + +## Pipeline Configuration Changes + +Pipeline configuration (YAML syntax) changes follow a strict deprecation process to ensure users have sufficient time to migrate. + +### Process Timeline + +1. **Minor Version N.x - Add Deprecation Warning** + - Linter shows a warning (not an error) + - Old syntax remains functional + - Documentation is updated to reflect the new syntax + - Warning message includes guidance on required changes + +2. **Major Version (N+1).0 - Warning Becomes Error** + - Linter issues an error (pipeline fails) + - Old syntax is no longer supported + - Breaking change is documented in the migration guide + - Users **must** update their configurations + +3. **Minor Version (N+1).x - Code Cleanup** + - Deprecated code paths are removed + - Implementation is simplified/refactored + - Parser no longer recognizes the old syntax + +### Example + +Old syntax: `secrets: [token]` +New syntax: `environment: { TOKEN: { from_secret: token } }` + +- **v2.5.0:** Deprecation warning added in linter; both syntaxes work +- **v2.6-2.9:** Warning persists; both syntaxes remain functional +- **v3.0.0:** Linter error; old syntax fails (breaking change) +- **v3.1.0:** Deprecated code paths removed; parser simplified + +### Implementation Checklist + +When deprecating pipeline configuration syntax, ensure the following: + +- [ ] Add linter warning in `/pipeline/frontend/yaml/linter/` +- [ ] Update JSON schema in `/pipeline/frontend/yaml/linter/schema` +- [ ] Add test cases for deprecated syntax +- [ ] Update documentation to reflect the new syntax