From 485c23fc243e8593e4f9db1c3061c2eeb2498c39 Mon Sep 17 00:00:00 2001 From: Lance Wray Date: Mon, 29 Jun 2026 09:17:04 +0000 Subject: [PATCH 1/3] Initial releases.md documentation --- releases.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 releases.md diff --git a/releases.md b/releases.md new file mode 100644 index 000000000..afafb4f85 --- /dev/null +++ b/releases.md @@ -0,0 +1,49 @@ +# Release Strategy & Documentation + +This document outlines the versioning scheme, release classification, and release automation process for the `stellar-engine` repository. + +--- + +## 📌 Release Classification & Versioning Scheme + +`stellar-engine` follows Semantic Versioning (`vMAJOR.MINOR.PATCH`). Releases are categorized based on their impact on underlying Terraform state and deployed infrastructure resources. + +### 🔴 Major Releases (`vX.0.0`) +* **Definition**: Any changes that require: + * Terraform state manipulation (e.g., manual state modification, removals). + * Terraform state moves (`terraform state mv` or refactoring existing resource addresses). + * Redeployment or recreation of existing infrastructure resources. +* **Process**: Executed **manually**. +* **Upgrade Guidance**: Major releases will include detailed migration notes, state refactoring scripts, or step-by-step instructions for upgrading existing environments without unexpected downtime or state drift. + +### 🔵 Minor Releases (`vX.Y.0`) +* **Definition**: Feature additions, enhancements, or updates that do **not** require Terraform state manipulation, state moves, or redeployment of existing resources (e.g., backwards-compatible infrastructure additions, non-destructive parameter updates). +* **Process**: Generated **monthly automatically** from the `main` branch. + +### 🟢 Patch Releases (`vX.Y.Z`) +* **Definition**: Critical bug fixes, security patches, or urgent non-breaking adjustments. +* **Process**: Executed on an **ad-hoc** basis, where the release is updated and tagged **manually**. + +--- + +## 🔄 Release Cadence & Automation Summary + +| Release Type | Trigger / Cadence | Execution | State Manipulation / Redeploy Required? | +| :--- | :--- | :--- | :--- | +| **Major** (`vX.0.0`) | As needed | Manual | **Yes** | +| **Minor** (`vX.Y.0`) | Monthly | Automated (from `main`) | **No** | +| **Patch** (`vX.Y.Z`) | Ad-hoc / As needed | Manual | **No** | + +--- + +## 🛠️ Contributor Guidelines & Release Workflow + +To ensure smooth automated and manual releases, contributors must adhere to the following workflow: + +1. **Pull Request Impact Assessment**: + * PR authors must explicitly state whether their proposed changes require state manipulation, state moves, or resource redeployment. + * If a PR introduces breaking state changes or resource redeployments, it must be flagged for inclusion in an upcoming **Major Release**. +2. **Main Branch Readiness**: + * All changes merged into the `main` branch should be tested and production-ready, as automated **Minor Releases** are generated directly from `main` on a monthly schedule. +3. **Patch / Hotfix Workflow**: + * Urgent fixes requiring a **Patch Release** are tagged manually ad-hoc against the affected version target and merged back to `main`. From 1c423070cd5648c739be246b4e0201c60490bee6 Mon Sep 17 00:00:00 2001 From: Lance Wray Date: Mon, 13 Jul 2026 15:19:18 +0000 Subject: [PATCH 2/3] remove icons, bolding, amperstands and add intro sentence for each header --- releases.md | 55 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 32 insertions(+), 23 deletions(-) diff --git a/releases.md b/releases.md index afafb4f85..897262895 100644 --- a/releases.md +++ b/releases.md @@ -1,49 +1,58 @@ -# Release Strategy & Documentation +# Release Strategy and Documentation This document outlines the versioning scheme, release classification, and release automation process for the `stellar-engine` repository. --- -## 📌 Release Classification & Versioning Scheme +## Release Classification and Versioning Scheme `stellar-engine` follows Semantic Versioning (`vMAJOR.MINOR.PATCH`). Releases are categorized based on their impact on underlying Terraform state and deployed infrastructure resources. -### 🔴 Major Releases (`vX.0.0`) -* **Definition**: Any changes that require: +### Major Releases + +Major releases (e.g., `vX.0.0`) cover breaking changes or updates that require state manipulation or resource redeployment. + +* Definition: Any changes that require: * Terraform state manipulation (e.g., manual state modification, removals). * Terraform state moves (`terraform state mv` or refactoring existing resource addresses). * Redeployment or recreation of existing infrastructure resources. -* **Process**: Executed **manually**. -* **Upgrade Guidance**: Major releases will include detailed migration notes, state refactoring scripts, or step-by-step instructions for upgrading existing environments without unexpected downtime or state drift. +* Process: Executed manually. +* Upgrade Guidance: Major releases will include detailed migration notes, state refactoring scripts, or step-by-step instructions for upgrading existing environments without unexpected downtime or state drift. + +### Minor Releases + +Minor releases (e.g., `vX.Y.0`) cover backwards-compatible feature additions, updates, and enhancements. + +* Definition: Feature additions, enhancements, or updates that do not require Terraform state manipulation, state moves, or redeployment of existing resources (e.g., backwards-compatible infrastructure additions, non-destructive parameter updates). +* Process: Generated monthly automatically from the `main` branch. + +### Patch Releases -### 🔵 Minor Releases (`vX.Y.0`) -* **Definition**: Feature additions, enhancements, or updates that do **not** require Terraform state manipulation, state moves, or redeployment of existing resources (e.g., backwards-compatible infrastructure additions, non-destructive parameter updates). -* **Process**: Generated **monthly automatically** from the `main` branch. +Patch releases (e.g., `vX.Y.Z`) cover critical bug fixes, security patches, and urgent non-breaking adjustments. -### 🟢 Patch Releases (`vX.Y.Z`) -* **Definition**: Critical bug fixes, security patches, or urgent non-breaking adjustments. -* **Process**: Executed on an **ad-hoc** basis, where the release is updated and tagged **manually**. +* Definition: Critical bug fixes, security patches, or urgent non-breaking adjustments. +* Process: Executed on an ad-hoc basis, where the release is updated and tagged manually. --- -## 🔄 Release Cadence & Automation Summary +## Release Cadence and Automation Summary | Release Type | Trigger / Cadence | Execution | State Manipulation / Redeploy Required? | | :--- | :--- | :--- | :--- | -| **Major** (`vX.0.0`) | As needed | Manual | **Yes** | -| **Minor** (`vX.Y.0`) | Monthly | Automated (from `main`) | **No** | -| **Patch** (`vX.Y.Z`) | Ad-hoc / As needed | Manual | **No** | +| Major (`vX.0.0`) | As needed | Manual | Yes | +| Minor (`vX.Y.0`) | Monthly | Automated (from `main`) | No | +| Patch (`vX.Y.Z`) | Ad-hoc / As needed | Manual | No | --- -## 🛠️ Contributor Guidelines & Release Workflow +## Contributor Guidelines and Release Workflow To ensure smooth automated and manual releases, contributors must adhere to the following workflow: -1. **Pull Request Impact Assessment**: +1. Pull Request Impact Assessment: * PR authors must explicitly state whether their proposed changes require state manipulation, state moves, or resource redeployment. - * If a PR introduces breaking state changes or resource redeployments, it must be flagged for inclusion in an upcoming **Major Release**. -2. **Main Branch Readiness**: - * All changes merged into the `main` branch should be tested and production-ready, as automated **Minor Releases** are generated directly from `main` on a monthly schedule. -3. **Patch / Hotfix Workflow**: - * Urgent fixes requiring a **Patch Release** are tagged manually ad-hoc against the affected version target and merged back to `main`. + * If a PR introduces breaking state changes or resource redeployments, it must be flagged for inclusion in an upcoming Major Release. +2. Main Branch Readiness: + * All changes merged into the `main` branch should be tested and production-ready, as automated Minor Releases are generated directly from `main` on a monthly schedule. +3. Patch / Hotfix Workflow: + * Urgent fixes requiring a Patch Release are tagged manually ad-hoc against the affected version target and merged back to `main`. From a3560e43825b309bbbc3690b1064ca0ed7327a4f Mon Sep 17 00:00:00 2001 From: Lance Wray Date: Mon, 13 Jul 2026 18:44:19 +0000 Subject: [PATCH 3/3] add last friday of each month as the minor release point --- releases.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/releases.md b/releases.md index 897262895..71e2eec8f 100644 --- a/releases.md +++ b/releases.md @@ -2,8 +2,6 @@ This document outlines the versioning scheme, release classification, and release automation process for the `stellar-engine` repository. ---- - ## Release Classification and Versioning Scheme `stellar-engine` follows Semantic Versioning (`vMAJOR.MINOR.PATCH`). Releases are categorized based on their impact on underlying Terraform state and deployed infrastructure resources. @@ -24,7 +22,7 @@ Major releases (e.g., `vX.0.0`) cover breaking changes or updates that require s Minor releases (e.g., `vX.Y.0`) cover backwards-compatible feature additions, updates, and enhancements. * Definition: Feature additions, enhancements, or updates that do not require Terraform state manipulation, state moves, or redeployment of existing resources (e.g., backwards-compatible infrastructure additions, non-destructive parameter updates). -* Process: Generated monthly automatically from the `main` branch. +* Process: Generated monthly on the last Friday of the month automatically from the `main` branch. ### Patch Releases @@ -33,7 +31,6 @@ Patch releases (e.g., `vX.Y.Z`) cover critical bug fixes, security patches, and * Definition: Critical bug fixes, security patches, or urgent non-breaking adjustments. * Process: Executed on an ad-hoc basis, where the release is updated and tagged manually. ---- ## Release Cadence and Automation Summary @@ -43,7 +40,6 @@ Patch releases (e.g., `vX.Y.Z`) cover critical bug fixes, security patches, and | Minor (`vX.Y.0`) | Monthly | Automated (from `main`) | No | | Patch (`vX.Y.Z`) | Ad-hoc / As needed | Manual | No | ---- ## Contributor Guidelines and Release Workflow