Release Management
Purpose
This page documents the release management process for Maqsafy services.
The purpose is to control changes, reduce deployment risk, improve traceability, and ensure that every production release is tested, approved, documented, and recoverable.
Release Management Scope
This process applies to:
- Backend releases
- Frontend releases
- Dashboard releases
- Mobile app releases
- Database migrations
- Infrastructure changes
- Security patches
- Configuration changes
- Integration changes
Release Principles
- Every production release must have a clear owner.
- Every release must have a documented scope.
- Every release must be tested before production deployment.
- Every release must have rollback instructions.
- Every release must document database migrations.
- Every release must document operational risks.
- Sensitive data must not be included in release notes.
- Production deployment must not be performed without backup confirmation.
Versioning
Use a clear versioning scheme for releases.
Recommended format:
MAJOR.MINOR.PATCH
Example:
1.4.2
Semantic Versioning defines version numbers as MAJOR.MINOR.PATCH, where each part communicates the type of change being released. It also states that once a versioned package has been released, that release content must not be modified; changes should be released as a new version.
Version Change Rules
| Change Type | Version Impact | Example |
|---|---|---|
| Breaking change | MAJOR | 2.0.0 |
| New feature without breaking existing behavior | MINOR | 1.5.0 |
| Bug fix or hotfix | PATCH | 1.4.3 |
Release Types
| Release Type | Description | Example |
|---|---|---|
| Major Release | Large release with breaking or structural changes | New platform module |
| Minor Release | New feature or enhancement | New report or workflow |
| Patch Release | Bug fix with limited scope | Fix dashboard display issue |
| Hotfix | Urgent production fix | Fix login failure |
| Security Release | Fix for security vulnerability | Patch access control issue |
| Infrastructure Release | Server, Nginx, Docker, Redis, or database infrastructure change | Update Nginx config |
Branching Rules
| Branch | Purpose |
|---|---|
| main / production | Stable production-ready code |
| staging | Pre-production validation |
| develop | Active development, if used |
| feature/* | Feature development |
| hotfix/* | Urgent production fixes |
| release/* | Release preparation, if used |
Pull Request Rules
Every code change should go through review before merging.
Pull request checklist:
| Check | Required |
|---|---|
| Clear change description | Yes |
| Linked requirement or issue | Yes |
| Code review completed | Yes |
| Tests passed | Yes |
| Security impact reviewed | Yes |
| Database migration reviewed | If applicable |
| Rollback impact reviewed | Yes |
| Documentation updated | If applicable |
Pre-Release Checklist
Before releasing to production, confirm:
| Item | Status |
|---|---|
| Release owner assigned | TBD |
| Release scope documented | TBD |
| Requirements linked | TBD |
| Code review completed | TBD |
| Tests passed | TBD |
| RBAC impact reviewed | TBD |
| Tenant isolation impact reviewed | TBD |
| Database migrations reviewed | TBD |
| Backup confirmed | TBD |
| Rollback plan documented | TBD |
| Environment variables reviewed | TBD |
| Queue workers impact reviewed | TBD |
| Integration impact reviewed | TBD |
| Monitoring and alerts checked | TBD |
| Release notes prepared | TBD |
Testing Requirements
Each release should include the relevant tests:
| Test Type | Required When |
|---|---|
| Unit tests | Code logic changes |
| Feature tests | Workflow changes |
| API tests | API changes |
| RBAC tests | Permission or role changes |
| Cross-tenant tests | Any scoped data access change |
| Regression tests | Any production release |
| Security tests | Auth, finance, credential, or input changes |
| Performance tests | Reports, exports, or heavy queries |
| Backup / restore validation | High-risk database changes |
Database Migration Review
Any migration must be reviewed before production release.
Migration checklist:
| Check | Required |
|---|---|
| Migration reviewed by developer | Yes |
| Migration tested on staging | Yes |
| Backup confirmed before production | Yes |
| Rollback strategy documented | Yes |
| Large table impact reviewed | Yes |
| Destructive operation avoided or approved | Yes |
| Expected execution time estimated | Yes |
| Index impact reviewed | Yes |
Deployment Steps
Use the actual deployment process for the environment.
General Laravel placeholder:
git pull
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:restart
Maintenance Mode
Use maintenance mode only when the release requires user traffic to stop temporarily.
Example placeholder:
php artisan down
Return the system online:
php artisan up
Laravel documents maintenance mode for temporarily preventing users from accessing the application during maintenance or deployment operations.
Queue Worker Handling
After deployment, restart queue workers gracefully:
php artisan queue:restart
Queue restart is required when workers need to reload the updated application code or configuration.
Post-Deployment Checklist
After deployment, verify:
| Check | Expected Result |
|---|---|
| Homepage or health endpoint | Responds successfully |
| Login | Works |
| Protected API endpoint | Works |
| Dashboard page | Loads correctly |
| Queue workers | Processing jobs |
| Redis | Reachable |
| Database | Reachable |
| Nginx | No config errors |
| Logs | No new critical errors |
| Integrations | No critical failures |
| Monitoring | No critical alerts |
| Reports / exports | Work if impacted |
| Payments / wallet | Work if impacted |
| Credential flows | Work if impacted |
Rollback Plan
Every release must have a rollback plan.
Rollback plan fields:
| Field | Description |
|---|---|
| Previous version | Last stable version |
| Code rollback command | How to return code |
| Database rollback | Whether migration rollback is safe |
| Configuration rollback | Required config changes |
| File rollback | Required static or uploaded file changes |
| Owner | Person responsible |
| Approval | Who approves rollback |
| Verification | How to confirm rollback success |
Example placeholder:
git checkout <previous-release-tag>
composer install --no-dev --optimize-autoloader
php artisan queue:restart
Release Notes Template
Use this format for every release:
## Version X.Y.Z - YYYY-MM-DD
### Summary
Short release summary.
### Changes
- Change 1
- Change 2
- Change 3
### Impacted Areas
- Backend
- Frontend
- Database
- API
- Queue
- Integrations
### Database Changes
- Migration name: TBD
- Rollback safe: Yes / No / Needs confirmation
### Security Impact
- RBAC impact: Yes / No
- Tenant isolation impact: Yes / No
- Sensitive data impact: Yes / No
### Testing Completed
- Unit tests: Yes / No
- API tests: Yes / No
- RBAC tests: Yes / No
- Regression tests: Yes / No
### Deployment Notes
- Deployment owner: TBD
- Deployment time: TBD
- Rollback owner: TBD
### Known Issues
- TBD
Hotfix Process
Hotfixes are urgent production fixes.
Hotfix rules:
- Scope must be limited.
- Root cause must be documented.
- Risk must be reviewed quickly.
- Fix must be tested before production.
- Deployment must be logged.
- Full post-release review must happen after stabilization.
Security Release Process
Security releases require stricter handling.
Security release checklist:
| Check | Required |
|---|---|
| Vulnerability documented internally | Yes |
| Affected systems identified | Yes |
| Exploit risk assessed | Yes |
| Fix tested | Yes |
| Secrets rotated if needed | Yes |
| Logs reviewed if needed | Yes |
| External disclosure reviewed if needed | Yes |
| Post-fix verification completed | Yes |
Release Approval Matrix
| Release Type | Approval Required |
|---|---|
| Patch | Technical owner |
| Minor | Technical owner + product owner |
| Major | Technical owner + product owner + business owner |
| Hotfix | Technical owner |
| Security | Technical owner + security owner / management |
| Database destructive change | Technical owner + management approval |
Release Log
Use this table to track releases:
| Version | Date | Type | Owner | Status | Notes |
|---|---|---|---|---|---|
| TBD | TBD | TBD | TBD | TBD | TBD |
Open Items
| Item | Status | Notes |
|---|---|---|
| Confirm versioning scheme | TBD | SemVer recommended |
| Confirm branching strategy | TBD | Replace placeholders |
| Confirm release approvers | TBD | Required |
| Confirm deployment owner | TBD | Required |
| Confirm rollback process | TBD | Required |
| Confirm hotfix process | TBD | Required |
| Confirm release note storage location | TBD | Required |
| Confirm production maintenance window | TBD | Required |
Rules
- Do not release without testing.
- Do not release without rollback plan.
- Do not release without backup confirmation when database changes are included.
- Do not include secrets in release notes.
- Do not include real customer data in release notes.
- Do not modify an already released version; publish a new version instead.
- Do not deploy high-risk changes during peak time unless approved.