Change Management Policy

Effective Date: 2026-03-02 Last Review: 2026-03-02 Next Review: 2026-09-02 Owner: Greg Felice, Project Lead

1. Purpose

This policy defines how changes to the tomo codebase, infrastructure, and services are proposed, reviewed, tested, approved, and deployed. It ensures that changes are tracked, reversible, and do not introduce unintended security or stability regressions.

2. Scope

This policy applies to:

• SDK code changes — all modifications to the tomo Python package (src/tomo/)
• Docker image changes — Dockerfile, build scripts, base image updates
• Infrastructure changes — server configuration, Ansible playbooks, nginx, Authentik, PostgreSQL
• CI/CD pipeline changes — Woodpecker pipeline configs, build scripts, secrets
• Documentation changes — security policies, runbooks, architecture docs
• Dependency changes — adding, removing, or updating third-party packages

3. Change Categories

Category	Risk Level	Approval Required	Examples
Standard	Low	PR review + CI pass	Documentation updates, test additions, minor refactors
Normal	Medium	PR review + CI pass + maintainer approval	Feature additions, dependency updates, API changes
Significant	High	PR review + CI pass + Project Lead approval	Security control changes, database schema changes, infrastructure changes
Emergency	Critical	Post-hoc review (within 24 hours)	Active incident remediation, critical vulnerability patch

4. Standard Change Process

4.1 Proposal

1. Create a branch from main (or fork for external contributors)
2. Implement changes with appropriate tests
3. Open a pull request on Forgejo (or GitHub for community contributions)
4. PR description must include:
5. What — Summary of the change
6. Why — Motivation or linked issue
7. Testing — How the change was tested
8. Security impact — Whether the change affects security controls (if applicable)

4.2 Automated CI Gates

All pull requests must pass the following Woodpecker CI checks before merge:

Gate	Tool	Blocks Merge	Purpose
Lint	ruff	Yes	Code style and error detection
Type check	mypy	Yes	Static type safety
Unit tests	pytest	Yes	Functional correctness (no DB required)
Integration tests	pytest -m integration	Yes	End-to-end correctness (requires PG18 + AGE)
Security lint	bandit	Yes (medium+ findings)	Static application security testing (SAST)
Dependency audit	pip-audit	Yes (known CVEs)	Supply chain vulnerability detection
Secret scan	trufflehog	Yes (any findings)	Prevent credential leaks
Container scan	trivy	Yes (critical/high CVEs)	Docker image vulnerability scan (main branch only)

4.3 Code Review

Review requirements by change category:

Category	Reviewers Required	Who Can Approve
Standard	1	Any maintainer
Normal	1	Maintainer or Project Lead
Significant	1 (Project Lead)	Project Lead only

Review checklist:

• [ ] Code is clear and well-structured
• [ ] Tests cover the change adequately
• [ ] No hardcoded secrets, credentials, or tokens
• [ ] Dependencies are justified and from trusted sources
• [ ] Error handling is appropriate
• [ ] Security implications considered (input validation, access control, data exposure)
• [ ] Backward compatibility maintained (or breaking change is documented)
• [ ] Documentation updated if user-facing behavior changed

4.4 Merge and Deploy

1. PR approved and all CI gates pass
2. Squash-merge to main (preserves clean history)
3. CI automatically runs on main branch (full test suite + container scan)
4. Tagged releases trigger automated publishing:
5. SDK: build and publish to PyPI
6. Docker image: build, scan, and push to Docker Hub
7. Infrastructure changes deployed via Ansible (manual trigger with approval)

5. Infrastructure Change Process

Infrastructure changes follow additional controls due to their direct impact on security and availability.

5.1 Configuration Changes

Change Type	Process
Ansible playbook update	PR review, test in staging (if available), deploy with --check first
nginx configuration	PR review, nginx -t validation, staged reload
PostgreSQL configuration	PR review, parameter impact assessment, scheduled maintenance window
Firewall rules	PR review, Project Lead approval, verify connectivity after change
Authentik configuration	PR review, Project Lead approval, test SSO flow post-change

5.2 Database Schema Changes

1. Schema changes documented in migration files (version-controlled)
2. Tested against a copy of production data (or representative test data)
3. Backup taken immediately before applying to production
4. Applied during scheduled maintenance window
5. Rollback script prepared and tested before execution

6. Emergency Change Process

When an active incident or critical vulnerability requires immediate action:

6.1 Authorization

1. Emergency changes may bypass PR review and CI gates
2. The Incident Commander (or Project Lead) authorizes the change verbally or via secure messaging
3. Changes are applied directly to the affected system

6.2 Documentation Requirements

Within 24 hours of the emergency change:

1. Create a retroactive PR documenting the change
2. Ensure CI passes on the retroactive PR
3. Document the justification in the incident record
4. Review whether the emergency change introduced any regressions
5. Rotate any credentials that were handled outside normal procedures

6.3 Post-Emergency Review

1. Include the emergency change process in the post-incident review
2. Evaluate whether the change could have been handled through normal process
3. Update runbooks if a new emergency pattern was identified

7. Rollback Procedures

Every change should be reversible. Rollback strategies by change type:

Change Type	Rollback Method	Target Time
SDK release	Yank version from PyPI, publish patched version	1 hour
Docker image	Retag previous known-good image, push to Docker Hub	30 minutes
Application code	git revert + merge to main + redeploy	1 hour
Infrastructure config	Ansible rollback playbook or manual config restore	1 hour
Database schema	Execute prepared rollback migration	2 hours
PostgreSQL config	Restore previous postgresql.conf, reload/restart	30 minutes
Firewall rules	Restore previous UFW rules from version control	15 minutes

7.1 Rollback Decision Criteria

Initiate rollback when:

• Change causes service outage or degradation
• Monitoring shows anomalous behavior post-change
• Security vulnerability introduced by the change
• Data integrity issue detected

8. Dependency Management

8.1 Adding Dependencies

Before adding a new dependency:

1. Justify — Document why the dependency is needed (no alternatives in stdlib or existing deps)
2. Evaluate — Check license compatibility (Apache 2.0 compatible), maintenance status, security history
3. Pin — Add with version constraint in pyproject.toml
4. Scan — Verify no known CVEs via pip-audit

8.2 Updating Dependencies

• Automated: Dependency update PRs (Renovate/Dependabot, when configured)
• Manual: Quarterly dependency review
• Security: Immediate update for dependencies with known exploited CVEs
• All updates go through standard PR process with full CI

8.3 Removing Dependencies

1. Remove from pyproject.toml and all import references
2. Verify no transitive dependents rely on it
3. Update documentation

9. Release Process

9.1 SDK Releases

1. Update version in pyproject.toml
2. Update CHANGELOG
3. Create PR with version bump, ensure all CI passes
4. Merge to main
5. Create Git tag (vX.Y.Z)
6. CI automatically builds and publishes to PyPI
7. Verify published package installs correctly

9.2 Docker Image Releases

1. Update version references in Dockerfile and docker-compose
2. Build and test image locally
3. Create PR, ensure all CI passes (including trivy scan)
4. Merge to main
5. CI automatically builds, scans, and pushes to Docker Hub
6. Verify published image pulls and runs correctly

10. Audit Trail

All changes are tracked through:

Record	Location	Retention
Git commit history	Forgejo, GitHub	Indefinite
Pull request records	Forgejo, GitHub	Indefinite
CI build logs	Woodpecker	90 days
Deploy logs	Ansible logs, systemd journal	90 days
Infrastructure change log	Git (Ansible repo)	Indefinite

11. Compliance Mapping

SOC 2 Criteria	Control
CC8.1	Change management process and controls
CC6.1	Logical access controls during changes
CC7.1	Detection of unauthorized changes
CC7.2	Monitoring of changes to system components
CC3.4	Assessment of changes that could impact controls