Change Management Policy

Version: 1.0 Last Updated: February 2026

---

1. Purpose

This policy governs how changes to the Nova IAM application, infrastructure, and configuration are planned, approved, tested, and deployed.

2. Change Categories

Category	Definition	Examples	Approval Required
Standard	Pre-approved, low-risk, routine changes	Dependency updates, minor UI fixes, log level changes	Peer review
Normal	Planned changes with moderate impact	New features, API changes, schema migrations	Team lead + peer review
Emergency	Urgent fixes for active incidents	Security patches, critical bug fixes, data corruption fixes	Post-hoc review within 24h

3. Change Process

3.1 Request

• All changes are tracked via version control (Git)
• Each change requires a descriptive commit message explaining the "why"
• Feature branches are used for non-trivial changes

3.2 Review

• All code changes require peer review before merging
• Security-sensitive changes (auth, crypto, data handling) require security team review
• Database schema changes require DBA review
• Review checklist:
  • No hardcoded credentials or secrets
  • Parameterized database queries (no string interpolation)
  • Input validation on new API endpoints
  • Audit logging for new security-relevant operations
  • Backward compatibility for API changes
  • Migration is idempotent (can be re-run safely)

3.3 Testing

• Automated test suite must pass before deployment
• Linting checks (Ruff) must pass
• Manual testing for UI changes
• Security review for authentication/authorization changes

3.4 Deployment

• Database backup taken before schema-altering deployments
• Deployments executed during maintenance windows for major changes
• Rollback procedure documented and tested
• Post-deployment verification checklist:
  • Application starts without errors
  • Database migrations completed successfully
  • Authentication flow working
  • Backend system connectivity verified
  • Audit logging active

3.5 Post-Deployment

• Monitor audit logs for anomalies (1 hour minimum)
• Verify key functionality via smoke tests
• Document any issues encountered and resolutions

4. Database Migration Standards

All database changes in Nova IAM follow these standards:

Idempotent Migrations

• CREATE TABLE IF NOT EXISTS for new tables
• ALTER TABLE ADD COLUMN wrapped in DO $$ ... EXCEPTION WHEN duplicate_column blocks
• Migrations can be safely re-run without side effects

Migration Ordering

Migrations execute in defined phases on application startup:

1. Phase 1: Schema creation and alterations
2. Phase 2: Data migrations and backfills
3. Phase 3: Seed data (only when tables are empty)
4. Phase 4: Runtime fixups

Rollback Strategy

• Non-destructive migrations: no rollback needed (additive changes)
• Destructive migrations: manual rollback scripts prepared and tested before deployment
• Database snapshots taken before all schema changes

5. Version Control Standards

• All source code managed in Git
• Commit messages follow conventional format: type + concise description
• No secrets, credentials, or .env files committed to the repository
• .gitignore maintained to exclude sensitive and generated files
• Tags used for release versions