From 386dbbf453175660f902fca49a34115ad43b4ace Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Fischer?= Date: Mon, 21 Jul 2025 09:42:36 +0200 Subject: [PATCH] docs(releases.md): Add release and patch management process --- README.md | 2 + docs/releases.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 docs/releases.md diff --git a/README.md b/README.md index 57b9b177..d619b228 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,8 @@ Find out more about the permission system in the [roles & permissions concept](. # Releases +openDesk implements a defined [release and patch management process](./docs/releases.md) to ensure stability and security. + All technical releases are created using [Semantic Versioning](https://semver.org/). Gitlab provides an diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 00000000..b9148d4f --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,122 @@ + + +

Release Management

+ +This document outlines the release and patch management strategy for **openDesk**, ensuring that all updates, patches, and new releases are systematically **planned, tested, documented**, and **reliably deployed** into production. The process is designed to align with operational planning requirements and maintain system stability and security. + + +* [Release Cycle](#release-cycle) + * [Release Types](#release-types) + * [Release Schedule](#release-schedule) + * [Upgrades](#upgrades) +* [Patch Management Process](#application-administration) + * [Patch Identification & Prioritization](#patch-identification-prioritization) + * [Patch Workflow](#patch-workflow) +* [Communication Plan](#communication-plan) + * [Announcement Channels](#announcement-channels) + * [Timing of Communications](#timing-of-communications) +* [Documentation Requirements](#documentation-requirements) +* [Compliance & Review](#compliance-review) + + +# Release Cycle + +openDesk follows a structured release cycle to ensure predictability and reliability: + +## Release Types + +| Type | Frequency | Content | +|----------------|---------------|---------------------------------------------------------------| +| **Major** | Annually (Q3) | Large feature sets, architecture changes, breaking changes | +| **Minor** | Monthly | New features, enhancements, may contain breaking changes or refactors (clearly flagged in the notes) | +| **Patch** | On demand | Bug fixes, security updates, minor improvements, no intended breaking changes | + +> **Note:** openDesk does **not** guarantee that minor releases are 100% backward‑compatible. When a breaking change is unavoidable it is announced in the release notes under a dedicated header **“Breaking Changes”** and a migration guide is provided. + +## Release Schedule + +- **Major releases** are scheduled for **Q3 each year**, with planning beginning in Q1. +- **Minor releases** occur **monthly on Mondays**, typically **around 10:00 AM** local time. + - Each minor release follows a **4-week cycle**. + - **Week 1–3**: Active development of new features and improvements. + - **End of Week 3**: **Feature freeze** is enforced to allow stabilization and testing. + - **Week 4**: Final testing, approvals, and preparation for release. + - At the **end of Week 4**, a new minor version is released, and a new cycle begins. +- **Patch releases** are created **on demand**, based on criticality and urgency. + +## Upgrades + +- openDesk does not guarantee an in‑place upgrade between two major versions. Always consult the release notes and plan appropriate migration efforts. +- Even within the same major line, skipping multiple monthly minor versions is not guaranteed to work without intermediate upgrade steps. +- All breaking changes, including those in monthly minor releases, are highlighted in the release notes under Breaking Changes. +- Additional, non‑binding migration hints are collected in `migrations.md` + +# Patch Management Process + +A standardized process ensures patches are developed, prioritized, and deployed efficiently. + +## Patch Identification & Prioritization + +Patches are categorized by severity and urgency: + +| Priority Level | Criteria | +|----------------|--------------------------------------------------------------------------| +| **Critical** | Security vulnerabilities, system outages, data loss risks | +| **High** | Major bugs affecting multiple users, performance degradation | +| **Medium** | Functional bugs with workarounds, minor usability issues | +| **Low** | Cosmetic issues, documentation updates | + +## Patch Workflow + +The following steps define the patch workflow from issue identification to post-deployment review. This process ensures consistent quality and minimal disruption to users: + +1. **Identification**: Potential issues are detected through automated monitoring, internal testing, audits, or user reports submitted via the support ticketing system. +2. **Assessment**: The product and engineering teams triage the issue, determine severity based on business and user impact, and prioritize it within the patch queue. +3. **Development**: A fix is implemented on a dedicated feature or hotfix branch, adhering to coding standards and version control protocols. +4. **Testing**: All patches undergo automated unit and integration tests, as well as manual QA validation in a staging environment that closely mirrors production. +5. **Approval**: Once tested, the patch must be approved by the product owner or a designated release manager, with proper documentation and change control entries. +6. **Deployment**: The patch is rolled out using CI/CD pipelines during predefined deployment windows or as soon as possible for critical issues. +7. **Post-deployment review**: After deployment, the fix is verified in production, and monitoring tools are used to detect regressions or unintended side effects. + +This workflow ensures that patches are handled with the same level of discipline as planned releases, supporting both reliability and agility. + +# Communication Plan + +A lightweight approach reduces manual effort while maintaining transparency. + +## Announcement Channels + +| Channel | Audience | Purpose | Owner | +|---------|----------|---------|-------| +| **openCode Changelog** | Community & EE | Primary source of truth for every release | DevOps | +| **Account‑Manager Mail / Ticket** | Enterprise customers | Targeted information & upgrade advice | Customer Success | + +## Timing of Communications + +| Release Type | What | When | +|--------------|------|------| +| **Major** | Roadmap entry + migration highlights | 4 weeks before release | +| | Final confirmation | 1 week before release | +| **Minor** | Changelog entry (draft) | Immediately after feature freeze (end of week 3) | +| | EE mail/ticket | 2 business days before deployment | +| **Patch** | Changelog entry | Right after production deploy | +| | EE mail/ticket (only if impacted) | Within 1 business day | + +Community users consume information via openCode; Enterprise customers get an additional nudge via their account manager – **no mass mailings are sent manually**. + +# Documentation Requirements + +Each release (major, minor, or patch) must include: + +- **Release notes** outlining new features, fixes, and known issues +- **Change logs** with commit references and affected components +- **Test reports** confirming QA coverage and results +- **Deployment checklist** reviewed and approved by the product owner + +# Compliance & Review + +- The release process is reviewed **bi-annually** to incorporate feedback and evolving requirements +- Emergency patches (e.g., zero-day security issues) may bypass the standard schedule but must be documented post-deployment