Skip to content

Home Information - Your home, your data, organized.

Python

Update release process documentation with improved structure and validation steps

Tony Cassandracdcf7e4aa021
diff --git a/docs/dev/ReleaseProcesses.md b/docs/dev/ReleaseProcesses.md
index 1dd6efea..e5f75217 100644
--- a/docs/dev/ReleaseProcesses.md
+++ b/docs/dev/ReleaseProcesses.md
@@ -2,26 +2,90 @@
# Release Process
-## Preamble
-
-- Releases are only done by the core maintainers with direct repo access and not done on a fork of the repo.
-- All work is done in feature branches that get merged into the staging branch.
-- The master branch is the release branch.
-- The release process is mainly about merging the accumulated PRs in staging into master.
-
-## Step by Step
-
-- Change to `staging` branch locally.
-- Get your local `staging` branch fuly in sync with remote/upstream.
-- Bump the version number in the file `HI_VERSION` as appropriate: major, minor or suffix.
-- Commit the version number change directly to the upstream `staging` branch with "Bump version number to vX.X.X".
-- Change to local `master` branch.
-- Get your `master` branch fully in sync with remote/upstream.
-- Merge from `staging` into `master`
-- Push `master` to remote/upstream.
-- Create GitHub release.
-- Add/create tag with next version number in the form `vX.X.X`.
-- Set Target = `master`
-- Use "Generate release notes" button anmd edit as needed.
-- Use "Set as the latest release" (usually)
-- "Publish Release" button.
+## Overview
+
+Releases are managed through a structured branch workflow where:
+- All development work occurs in feature branches
+- Feature branches are merged into the `staging` branch via pull requests
+- The `master` branch serves as the release branch
+- Releases involve merging accumulated changes from `staging` into `master`
+
+## Prerequisites
+
+- Direct repository access (core maintainers only)
+- Local development environment properly configured
+- All target changes already merged into `staging` branch
+
+## Pre-Release Verification
+
+Before starting the release process, verify the staging branch is ready:
+
+1. **Confirm CI Status**: Ensure all GitHub Actions checks are passing on `staging`
+2. **Run Local Validation**: Execute tests and linting as a sanity check
+ ```bash
+ make check
+ ```
+3. **Review Recent Changes**: Check recent commits and merged PRs for any concerns
+
+## Release Steps
+
+### 1. Prepare Staging Branch
+- Switch to `staging` branch locally
+- Sync your local `staging` branch with remote/upstream:
+ ```bash
+ git checkout staging
+ git pull github staging
+ ```
+
+### 2. Update Version Number
+- Bump the version number in `HI_VERSION` file following semantic versioning
+- Commit the version change directly to upstream `staging`:
+ ```bash
+ git add HI_VERSION
+ git commit -m "Bump version number to vX.X.X"
+ git push github staging
+ ```
+
+### 3. Merge to Master
+- Switch to local `master` branch and sync with remote:
+ ```bash
+ git checkout master
+ git pull github master
+ ```
+- Merge from `staging` into `master`:
+ ```bash
+ git merge staging
+ git push github master
+ ```
+
+### 4. Create GitHub Release
+1. Navigate to the GitHub repository releases page
+2. Click "Create a new release"
+3. **Tag**: Create new tag in format `vX.X.X`
+4. **Target**: Set to `master` branch
+5. **Title**: Use the tag name (e.g., `v1.2.3`)
+6. **Description**: Use "Generate release notes" button and edit as needed
+7. **Settings**:
+ - Check "Set as the latest release" (typically)
+ - Leave "Set as a pre-release" unchecked (for stable releases)
+8. Click "Publish Release"
+
+## Future Considerations
+
+### Version Bumping Criteria
+**TBD** - Establish clear guidelines for when to increment:
+- Major version (breaking changes)
+- Minor version (new features, backward compatible)
+- Patch version (bug fixes, backward compatible)
+
+### Rollback Procedures
+**TBD** - Document rollback procedures for failed releases:
+- How to revert problematic releases
+- Communication protocols for rollback situations
+- Testing procedures post-rollback
+
+## Notes
+
+- **Changelog Management**: Release notes are generated from GitHub's automatic changelog feature rather than maintaining a separate changelog file
+- **Deployment**: Current releases are distributed as downloadable packages for self-installation
+- **Quality Assurance**: GitHub branch protection rules enforce passing tests and code quality checks before PRs can merge to `staging`