Change Management Policy

Version: 1.0 · Status: Active · Effective: 2026-05-05

1. Purpose

This policy defines the controls and processes that govern changes to Projan’s software systems. It ensures that all modifications to application code, shared libraries, and infrastructure are subject to review, automated verification, and controlled promotion through environments before reaching production.

2. Scope

This policy applies to all changes made to:

Application services and user-facing interfaces
Shared libraries and internal packages
Infrastructure-as-code definitions
Serverless functions and background workers
CI/CD pipeline configuration

All engineers, contractors, and automated systems that introduce changes to the Projan codebase are bound by this policy.

3. Change Process

Every change to the Projan codebase follows a structured pull request workflow:

Branch creation. A developer creates a feature branch from the main branch. Direct commits to the main branch are prohibited.
Pull request. The developer opens a pull request describing the change, its motivation, and any relevant context.
Mandatory code review. At least one other engineer must review and approve the pull request before it can be merged. Reviewers assess correctness, security implications, test coverage, and adherence to coding standards.
Automated verification. The continuous integration pipeline runs automatically on every pull request. All automated checks must pass before the pull request is eligible for merge.
Merge to main. Once approved and verified, the change is merged into the main branch, triggering automatic deployment to the development environment.

4. Pre-Commit Controls

Local development environments enforce code quality standards before changes enter the review process:

Automated linting. Pre-commit hooks run static analysis on all staged files, automatically correcting formatting issues and flagging violations of coding standards.
Consistent tooling. The pre-commit configuration ensures all developers use the same linting rules and Node.js version, regardless of their local setup.
Fail-fast approach. Code that does not meet quality standards is rejected at the commit stage, reducing the volume of issues that reach the pull request review.

These controls supplement but do not replace the CI pipeline checks, which run independently on the server side.

5. Continuous Integration

An automated CI pipeline runs on every pull request targeting the main branch. The pipeline enforces the following gates in sequence:

Linting. Static analysis runs across all projects to verify code quality, consistent formatting, and adherence to established patterns.
Testing. Automated test suites execute for all projects affected by the change. Only affected projects are tested, ensuring efficient use of CI resources while maintaining comprehensive coverage of impacted code paths.
Build verification. Affected projects are compiled and built to confirm that the change produces valid, deployable artifacts.

All three gates must pass before a pull request can be merged. If any gate fails, the pull request is blocked until the issue is resolved. The pipeline uses intelligent change detection to identify which projects within the monorepo are affected by a given change, ensuring that unrelated projects are not unnecessarily rebuilt or retested.

6. Deployment Pipeline

Projan operates a fully automated deployment pipeline that promotes changes through a defined sequence of environments.

Automatic deployment. When a change is merged to the main branch, the deployment pipeline automatically identifies affected services and deploys them to the development environment. No manual intervention is required for development deployments.

Service detection. The pipeline analyses the changeset to determine which services, applications, and infrastructure components require deployment. Only affected components are deployed, minimising deployment scope and risk.

Infrastructure-first ordering. When infrastructure changes are included in a deployment, they are applied before any application services are deployed. This ensures that application code always runs against the correct infrastructure configuration.

Manual promotion. Promotion to staging and production environments requires explicit action. Developers or release managers initiate promotion through a controlled release process that specifies the target environment, services, and version.

7. Deployment Safeguards

Multiple safeguards protect against failed or degraded deployments:

Health checks. All deployed services are monitored for health after deployment. The deployment process waits for the service to reach a stable, healthy state before reporting success.
Automatic rollback. If a newly deployed service fails to stabilise, the platform automatically rolls back to the previous healthy version. Failed deployments are flagged immediately for investigation.
Image verification. Before deploying a new version of a service, the pipeline verifies that the required build artifacts are available and valid. Deployments do not proceed until artifacts are confirmed.
Infrastructure change visibility. For non-development environments, infrastructure changes are analysed and the planned modifications are presented for review before they are applied. This provides an opportunity to catch unintended changes before they affect shared environments.
Approval gates. Production infrastructure changes require explicit approval based on the scope and nature of the modifications.

8. Environment Promotion

Projan maintains three deployment environments with a strict promotion path:

Environment	Purpose	Deployment Trigger
Development	Integration testing and early validation	Automatic on merge to main
Staging	Pre-production verification and acceptance testing	Manual promotion with release tagging
Production	Live customer-facing environment	Manual promotion with explicit approval

Production approval. All production deployments require explicit approval from an authorised team member. The approval gate ensures that production changes are intentional, reviewed, and scheduled appropriately.

Full verification on promotion. When promoting a release to staging or production, the pipeline runs a complete build and test cycle - not just the affected subset - to provide maximum confidence in the release.

Release tagging. Each promotion to staging or production is associated with a versioned release tag, providing a clear, auditable record of exactly which code is deployed to each environment.

9. Emergency Changes

Projan maintains procedures for emergency changes that require expedited deployment:

Emergency changes follow an abbreviated review process but still require approval from an authorised team member.
Emergency deployments are logged with the same audit trail as standard deployments.
A post-incident review is conducted for all emergency changes to identify root causes and determine whether process improvements are needed.
Emergency changes are limited to the minimum scope necessary to resolve the incident.

10. Audit Trail

All changes and deployments are recorded through multiple complementary mechanisms:

Version control history. Every change is captured in Git with full commit history, authorship, timestamps, and associated pull request discussions and approvals.
Deployment records. Each deployment generates a structured record capturing the service, environment, version, commit reference, timestamp, and the identity of the person or system that initiated the deployment. Production deployment records are retained for an extended period to support compliance requirements. Non-production records are retained for a shorter but still meaningful duration.
Release tags. Production deployments are associated with permanent release tags that provide a definitive record of what was deployed and when.
Pipeline execution logs. Full execution logs for all CI and deployment runs are retained, including build output, test results, infrastructure change summaries, and deployment progress.

11. Review Schedule

This policy is reviewed:

Annually, or
When significant changes are made to the CI/CD pipeline or deployment architecture, or
When new environments, deployment targets, or services are introduced.

Next scheduled review: 2027-05-05.

12. Contact

For questions about this policy or to report concerns related to change management processes, contact:

Email: security@projan.ai

Projan AI Ltd (Company No. 17196385)

Policies