From 172d66f767d3e0cb7ee374f40a8474e23c6dca91 Mon Sep 17 00:00:00 2001 From: "m.huber" Date: Thu, 5 Feb 2026 15:19:27 +0100 Subject: [PATCH 1/4] docs: explizite mention how we do config deprications --- 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 00000000000..8961c817971 --- /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 give users time to migrate. + +### Process Timeline + +1. **Minor Version N.x - Add Deprecation Warning** + - Linter shows warning (not error) + - Old syntax still works + - Documentation updated to show new syntax + - Warning message explains what to change + +2. **Major Version (N+1).0 - Warning Becomes Error** + - Linter shows error (pipeline fails) + - Old syntax no longer works + - Breaking change documented in migration guide + - Users MUST update their configs + +3. **Minor Version (N+1).x - Code Cleanup** + - Remove deprecated code paths + - Simplify/refactor implementation + - Parser no longer recognizes old syntax + +### Example + +Old syntax: `secrets: [token]` +New syntax: `environment: { TOKEN: { from_secret: token } }` + +- v2.5.0: Add deprecation warning in linter, both work +- v2.6-2.9: Warning continues, both still work +- v3.0.0: Error in linter, old syntax fails (BREAKING) +- v3.1.0: Remove old code paths, simplify parser + +### Implementation Checklist + +When deprecating pipeline config syntax: + +- [ ] Add linter warning in `/pipeline/frontend/yaml/linter/` +- [ ] Change json schema in `/pipeline/frontend/yaml/linter/schema` +- [ ] Add test cases for deprecated syntax +- [ ] Update documentation with new syntax From b80c9eec24e313e74bf609e6610ed4a62b78c094 Mon Sep 17 00:00:00 2001 From: 6543 <6543@obermui.de> Date: Mon, 16 Feb 2026 18:52:48 +0100 Subject: [PATCH 2/4] Update docs/docs/92-development/40-deprecations.md Co-authored-by: Robert Kaussow --- docs/docs/92-development/40-deprecations.md | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/docs/92-development/40-deprecations.md b/docs/docs/92-development/40-deprecations.md index 8961c817971..25eebb824e1 100644 --- a/docs/docs/92-development/40-deprecations.md +++ b/docs/docs/92-development/40-deprecations.md @@ -2,26 +2,26 @@ ## Pipeline Configuration Changes -Pipeline configuration (YAML syntax) changes follow a strict deprecation process to give users time to migrate. +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 warning (not error) - - Old syntax still works - - Documentation updated to show new syntax - - Warning message explains what to change + - 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 shows error (pipeline fails) - - Old syntax no longer works - - Breaking change documented in migration guide - - Users MUST update their configs + - 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** - - Remove deprecated code paths - - Simplify/refactor implementation - - Parser no longer recognizes old syntax + - Deprecated code paths are removed + - Implementation is simplified/refactored + - Parser no longer recognizes the old syntax ### Example From f4ab3baa0d5c94bb890d4742429e0b560be5e4af Mon Sep 17 00:00:00 2001 From: 6543 <6543@obermui.de> Date: Mon, 16 Feb 2026 18:53:02 +0100 Subject: [PATCH 3/4] Update docs/docs/92-development/40-deprecations.md Co-authored-by: Robert Kaussow --- docs/docs/92-development/40-deprecations.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/92-development/40-deprecations.md b/docs/docs/92-development/40-deprecations.md index 25eebb824e1..3b4a2214e0a 100644 --- a/docs/docs/92-development/40-deprecations.md +++ b/docs/docs/92-development/40-deprecations.md @@ -28,10 +28,10 @@ Pipeline configuration (YAML syntax) changes follow a strict deprecation process Old syntax: `secrets: [token]` New syntax: `environment: { TOKEN: { from_secret: token } }` -- v2.5.0: Add deprecation warning in linter, both work -- v2.6-2.9: Warning continues, both still work -- v3.0.0: Error in linter, old syntax fails (BREAKING) -- v3.1.0: Remove old code paths, simplify parser +- **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 From adef8e3361d28226d5fe2dbaeab20cda23111fbb Mon Sep 17 00:00:00 2001 From: 6543 <6543@obermui.de> Date: Mon, 16 Feb 2026 18:53:18 +0100 Subject: [PATCH 4/4] Update docs/docs/92-development/40-deprecations.md Co-authored-by: Robert Kaussow --- docs/docs/92-development/40-deprecations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/92-development/40-deprecations.md b/docs/docs/92-development/40-deprecations.md index 3b4a2214e0a..f19f17c8e65 100644 --- a/docs/docs/92-development/40-deprecations.md +++ b/docs/docs/92-development/40-deprecations.md @@ -35,9 +35,9 @@ New syntax: `environment: { TOKEN: { from_secret: token } }` ### Implementation Checklist -When deprecating pipeline config syntax: +When deprecating pipeline configuration syntax, ensure the following: - [ ] Add linter warning in `/pipeline/frontend/yaml/linter/` -- [ ] Change json schema in `/pipeline/frontend/yaml/linter/schema` +- [ ] Update JSON schema in `/pipeline/frontend/yaml/linter/schema` - [ ] Add test cases for deprecated syntax -- [ ] Update documentation with new syntax +- [ ] Update documentation to reflect the new syntax