Release Process
Release Process Documentation
Project: Conformo - GDPR Compliance Platform for Italian SMEs
Version: 1.0
Last Updated: 2025-11-01
Status: Active
Table of Contents
- Overview
- Release Workflow
- Versioning Strategy
- Using the Release Workflow
- Branch Strategy
- Troubleshooting
- Best Practices
Overview
Conformo uses an automated GitHub Actions workflow to manage version tagging, release creation, and production branch updates. This ensures consistent, traceable, and auditable releases.
Key Features
- ✅ Automated Tagging: Creates and pushes git tags from the main branch
- ✅ GitHub Releases: Automatically generates release notes from commits
- ✅ Production Branch: Merges tagged commits to production branch for deployment
- ✅ Validation: Ensures version format compliance and prevents duplicate tags
- ✅ Audit Trail: All actions are logged and visible in GitHub Actions history
Release Workflow
The release workflow (release.yml) automates the entire release process:
┌─────────────────────────────────────────────────────────────────┐
│ RELEASE WORKFLOW STEPS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [1] VALIDATE INPUT │
│ ├─ Check version format (vX.Y.Z) │
│ └─ Verify tag doesn't already exist │
│ │
│ [2] CREATE TAG │
│ ├─ Checkout main branch │
│ ├─ Create annotated git tag │
│ └─ Push tag to remote │
│ │
│ [3] CREATE GITHUB RELEASE │
│ ├─ Generate release notes from commits │
│ ├─ Append custom notes (if provided) │
│ └─ Publish release on GitHub │
│ │
│ [4] UPDATE PRODUCTION BRANCH │
│ ├─ Check if production branch exists │
│ ├─ Create or checkout production branch │
│ ├─ Merge tagged commit │
│ └─ Push to remote │
│ │
│ [5] GENERATE SUMMARY │
│ └─ Display completion summary with next steps │
│ │
└─────────────────────────────────────────────────────────────────┘
Versioning Strategy
Semantic Versioning
Conformo follows Semantic Versioning 2.0.0:
Format: vMAJOR.MINOR.PATCH
- MAJOR (
v2.0.0): Breaking changes, incompatible API changes - MINOR (
v1.1.0): New features, backward-compatible additions - PATCH (
v1.0.1): Bug fixes, backward-compatible fixes
Version Guidelines
| Change Type | Example | Version Increment |
|---|---|---|
| New major feature with breaking changes | Complete UI redesign | v1.0.0 → v2.0.0 |
| New feature (backward-compatible) | Add new dashboard widget | v1.0.0 → v1.1.0 |
| Bug fix (backward-compatible) | Fix form validation | v1.0.0 → v1.0.1 |
| Security patch | Fix authentication bug | v1.0.0 → v1.0.1 |
Pre-release Versions
For pre-release versions, append a suffix:
- Alpha:
v1.0.0-alpha.1 - Beta:
v1.0.0-beta.1 - Release Candidate:
v1.0.0-rc.1
Using the Release Workflow
Prerequisites
Before creating a release:
- ✅ All changes are merged to
mainbranch - ✅ CI/CD pipeline is passing
- ✅ Quality gates are satisfied
- ✅ Security scans show no critical vulnerabilities
- ✅ Documentation is updated
- ✅ Release notes are prepared (optional)
Step-by-Step Guide
1. Navigate to GitHub Actions
- Go to the repository: https://github.com/GrewingM/conformo
- Click on the Actions tab
- Select Release Management workflow from the left sidebar
2. Trigger the Workflow
- Click the Run workflow button (top right)
-
Fill in the required inputs:
Version (required):
- Format:
vX.Y.Z(e.g.,v1.0.0,v1.2.3) - Must not already exist as a tag
Release Notes (optional):
- Additional notes to append to auto-generated notes
- Example: “This release includes critical security fixes”
- Format:
- Click Run workflow to start
3. Monitor Progress
The workflow will:
- ✅ Validate the version format
- ✅ Create and push the git tag
- ✅ Generate a GitHub Release with automatic release notes
- ✅ Merge the tagged commit to the production branch
Progress can be monitored in the Actions tab. Each step shows real-time logs.
4. Verify Release
After successful completion:
- Check the tag: Navigate to Code → Tags to see the new tag
- Review the release: Go to Releases to see the published release with notes
- Verify production branch: Confirm the production branch contains the release commit
Branch Strategy
Conformo uses a three-branch strategy:
Main Branch (main)
- Purpose: Primary development branch
- Protection: Requires PR reviews, passing CI/CD
- Deployment: Automatic deployment to preview/staging
- Usage: All feature branches merge here
Production Branch (production)
- Purpose: Production-ready code
- Protection: Updated only by release workflow
- Deployment: Automatic deployment to production (Vercel)
- Usage: Contains only tagged releases
Feature Branches
- Naming:
feature/US-XXX-description,fix/bug-description - Lifecycle: Created from
main, merged back tomain - Deployment: No automatic deployment
Branch Flow Diagram
feature/US-001 ─┐
├──> main ──> [Tag v1.0.0] ──> production
feature/US-002 ─┘ │
└──> Vercel Production
Troubleshooting
Common Issues
Issue: “Tag already exists”
Error Message:
❌ Error: Tag v1.0.0 already exists
Solution:
- Choose a different version number
- Or delete the existing tag if it was created in error:
git tag -d v1.0.0 git push origin :refs/tags/v1.0.0
Issue: “Invalid version format”
Error Message:
❌ Error: Version must be in format vX.Y.Z (e.g., v1.0.0)
Solution:
- Ensure version starts with
v - Use three numbers separated by dots:
vMAJOR.MINOR.PATCH - Valid examples:
v1.0.0,v2.1.3,v10.0.1 - Invalid examples:
1.0.0(missing v),v1.0(missing patch),v1.0.0.0(too many parts)
Issue: “Production branch merge conflict”
Error Message:
error: failed to push some refs to 'origin'
Solution:
- Manually resolve conflicts on the production branch
- Re-run the workflow
Issue: “Insufficient permissions”
Error Message:
refusing to allow a GitHub App to create or update workflow
Solution:
- Ensure the workflow has
contents: writepermission - Check repository settings for Actions permissions
Debugging Steps
If the workflow fails:
- Check the logs: Open the failed workflow run and review each step’s output
- Verify permissions: Ensure GitHub Actions has write access
- Check branch protection: Review branch protection rules for main/production
- Validate inputs: Confirm version format is correct
- Review git state: Check for uncommitted changes or conflicts
Best Practices
Before Creating a Release
- Code Freeze: Stop merging new features to main
- Testing: Run full test suite including:
- Unit tests
- Integration tests
- End-to-end tests
- Security scans
- Documentation: Update:
- README.md
- CHANGELOG.md
- API documentation
- User guides
- Release Notes: Prepare release notes highlighting:
- New features
- Bug fixes
- Breaking changes
- Security updates
During Release
- Monitor: Watch the workflow execution
- Communicate: Notify the team when release starts
- Verify: Check each step completes successfully
After Release
- Smoke Tests: Run smoke tests on production:
- User authentication
- Core features
- API endpoints
- Monitor: Watch for:
- Error rates
- Performance metrics
- User feedback
- Documentation: Update:
- Release announcements
- User-facing changelog
- Communication: Announce the release:
- Internal team notification
- User announcement (if appropriate)
Release Checklist
Use this checklist for every release:
## Pre-Release
- [ ] All PRs merged to main
- [ ] CI/CD passing
- [ ] Security scans clean
- [ ] Documentation updated
- [ ] Release notes prepared
- [ ] Team notified
## Release
- [ ] Workflow triggered with correct version
- [ ] Tag created successfully
- [ ] GitHub Release published
- [ ] Production branch updated
- [ ] Deployment completed
## Post-Release
- [ ] Smoke tests passed
- [ ] Metrics normal
- [ ] Team notified
- [ ] User announcement (if needed)
Workflow Permissions
The release workflow requires the following permissions:
permissions:
contents: write # Create tags, update branches
pull-requests: write # Create PRs if needed
These are defined in the workflow file and granted automatically by GitHub Actions.
Examples
Example 1: Creating a Major Release
Version: v2.0.0
Release Notes: |
Major release with breaking changes:
- New authentication system
- Updated API endpoints (v2)
- Improved Italian localization
Breaking Changes:
- Old API endpoints deprecated
- Session management changed
Example 2: Creating a Patch Release
Version: v1.0.1
Release Notes: |
Bug fixes and security updates:
- Fixed login form validation
- Updated dependencies with security patches
- Improved error messages in Italian
Example 3: Creating a Minor Release
Version: v1.1.0
Release Notes: |
New features:
- Added compliance dashboard widget
- Improved data export functionality
- Enhanced mobile responsiveness
Integration with CI/CD
The release workflow integrates with Vercel deployment:
- Tag Created → GitHub Release created
- Production Branch Updated → Vercel detects change
- Vercel Builds → Production build triggered
- Vercel Deploys → New version live on production
Vercel Configuration
The production branch is configured in Vercel to deploy to production:
- Production Branch:
production - Preview Branches: All other branches
- Build Command: Defined in
vercel.json
Related Documentation
- SDLC Framework - Development process
- Technical Architecture - System design
- Definition of Done - Quality criteria
Support
For issues with the release process:
- Check this documentation first
- Review workflow logs in GitHub Actions
- Contact the development team lead
- Create an issue in the repository
Last Updated: 2025-10-31
Maintained By: Development Team
Review Cycle: After each sprint