Change management

<h2>Purpose</h2> <p>Ensure that every change to HiringCoachAI production systems is reviewed, tested, documented, and reversible.</p> <h2>Branching and release</h2> <ul><li><strong>Main branch:</strong> <code>master</code></li><li><strong>Feature branches:</strong> <code>feat/<em></code>, <code>fix/</em></code>, <code>chore/*</code>; branched from <code>master</code></li><li><strong>Preview deployments:</strong> Vercel can deploy pull requests to unique preview URLs when the PR workflow is used.</li><li><strong>Production:</strong> Merging to <code>master</code> triggers a production build on Vercel</li><li><strong>Rollback:</strong> Vercel &quot;Instant Rollback&quot; to any prior deploy; target rollback time ≤5 min</li></ul> <h2>Current change checks</h2> <p>Current change control is built from local pre-push checks, manual GitHub workflows, CODEOWNERS ownership records, and Security Officer approval before production release.</p> <p>1. <strong>Local pre-push gate:</strong> a pre-push git hook runs a fast local-checks command unless explicitly bypassed with an opt-out environment variable. 2. <strong>Fast local checks:</strong> the local-checks command runs TypeScript, changed-file ESLint, API-validation delta, unsafe-fetch delta, AI retention-flag delta, and compliance-document audits when relevant files change. 3. <strong>Full local checks:</strong> a full local-checks command adds the production build before release or major changes. 4. <strong>Major-change dependency support review:</strong> major changes include a review of required third-party libraries, SDKs, platform runtimes, and managed-service integrations before production release. Unsupported or end-of-life dependencies must be upgraded, replaced, removed from release scope, or covered by a documented time-bound exception. 5. <strong>GitHub checks:</strong> manual CI and scheduled/manual security workflows can run typecheck, lint, build, smoke, npm audit, Semgrep, CodeQL, SBOM, patch verification, unauthenticated ZAP baseline DAST, and compliance-audit jobs. 6. <strong>Documentation-review drills:</strong> drills covering business continuity, disaster recovery, joiner/mover/leaver, vendor, and change can be run locally or through the manual security workflow; each archives a dated record in the internal audit evidence set. 7. <strong>Code ownership:</strong> CODEOWNERS routes sensitive paths to the Security Officer when GitHub PR review is used.</p> <h2>Branch protection</h2> <p><code>master</code> is the only deploy branch. Current controls are:</p> <table><thead><tr><th>Control</th><th>Mechanism</th><th>Verification</th></tr></thead><tbody><tr><td>Direct push control</td><td>Push access is restricted to the Security Officer via repository access control. Major changes follow this change management policy.</td><td>Repo access settings; CODEOWNERS file</td></tr><tr><td>Code ownership</td><td>CODEOWNERS owns <code>*</code> and sensitive paths, routing PR review to the Security Officer when the PR workflow is used.</td><td>CODEOWNERS file</td></tr><tr><td>Local quality checks</td><td>Pre-push hook runs fast local checks; a full local-checks command is available.</td><td>Internal hook and script</td></tr><tr><td>Manual GitHub workflows</td><td>CI and security jobs are available through workflow dispatch.</td><td>GitHub Actions workflows</td></tr><tr><td>Force-push / deletion control</td><td>Prohibited by policy on <code>master</code>.</td><td>Internal change governance review</td></tr><tr><td>Linear history (preferred)</td><td>Preferred on <code>master</code>.</td><td>Internal change governance review</td></tr></tbody></table> <p><strong>Branch ownership and protection.</strong> CODEOWNERS routes sensitive paths to the Security Officer; force-push and direct deletion of protected branches are prohibited by policy and reviewed under change governance.</p> <p>Compensating controls at current scale:</p> <p>1. <strong>Restricted personnel:</strong> Source-code, customer-data, production, and vendor-dashboard access is restricted to authorized personnel with Security Officer approval. 2. <strong>CODEOWNERS ownership:</strong> all paths are owned by the Security Officer, with additional sensitive-path routing. 3. <strong>Local checks:</strong> pre-push and full local checks provide repeatable quality gates before push or release. 4. <strong>Audit review:</strong> <code>git log --pretty=fuller</code> is reviewed during internal audit for out-of-band commits.</p> <h2>Change categories</h2> <table><thead><tr><th>Category</th><th>Examples</th><th>Approval</th><th>Notification</th></tr></thead><tbody><tr><td><strong>Standard</strong></td><td>Bug fixes, UI tweaks, copy, dependency patch bumps</td><td>Reviewer approval</td><td>None</td></tr><tr><td><strong>Normal</strong></td><td>New features, schema additions, new API routes</td><td>Reviewer + Engineering Lead</td><td>Changelog entry</td></tr><tr><td><strong>Major</strong></td><td>Breaking API changes, data migration, auth changes, pricing changes</td><td>Security Officer + Engineering Lead</td><td>Customer notice using risk-appropriate timing and channels</td></tr><tr><td><strong>Emergency</strong></td><td>Security incident, production outage, critical bug</td><td>Security Officer (retroactive if needed)</td><td>Post-incident customer notice within 24 h; status page</td></tr></tbody></table> <h2>Deployment windows</h2> <ul><li>Standard/normal changes: any time; deploys are rolled out progressively by Vercel.</li><li>Major changes: deployed during low-traffic windows (default: weekdays 02:00-06:00 US-Eastern) or behind feature flags with gradual rollout.</li><li>Emergency changes: any time, with post-deploy verification and monitoring.</li></ul> <p>HiringCoachAI designs updates to avoid customer impact. Higher-risk changes use low-traffic windows, progressive rollout, feature flags where appropriate, post-deploy monitoring, and rollback to limit customer impact if an issue occurs.</p> <h2>Customer notification</h2> <ul><li><strong>Major</strong>: Customers are notified when a major change materially affects customer security, privacy, data handling, authentication/access-control behavior, retention/deletion behavior, AI provider or prompt-handling posture, sub-processor use, or breaking API behavior. Timing and channels are risk-based rather than a fixed advance-notice window. Channels may include customer email, in-app notice, or status page. A copy of every major-change notification is filed in the internal audit archive for customer-security-review evidence.</li><li><strong>Emergency / breaking</strong>: Post-hoc notice within 24 h where appropriate; root cause and remediation published when disclosure is warranted. Recorded in the internal emergency-change register.</li><li><strong>Security patches</strong>: Generally silent; disclosed in release notes or on <code>/status</code> if the patch was incident-driven.</li></ul> <h2>Version support</h2> <p>HiringCoachAI is a continuously-delivered cloud-hosted service; there are no versioned customer installs. We maintain a single production version; all customers are on the current release. Routine product updates are communicated through normal product channels when customer action or material customer impact exists; major-impact notices follow the criteria above. HiringCoachAI performs service updates within the cloud-hosted environment; institutions do not need to install packages, schedule local deployment windows, change endpoint software, or provide technical staff to complete routine updates.</p> <h2>Configuration management</h2> <ul><li>Runtime baselines are managed through Vercel and Google Cloud / Firebase managed services rather than first-party server or endpoint images.</li><li>Application configuration is held in environment variables managed by the hosting platform</li><li>Infrastructure configuration (Firestore Security Rules, Firestore indexes, Firebase configuration, hosting-platform configuration, framework configuration) is version-controlled</li><li>All configuration changes are tracked in git</li><li>Secrets are never committed; environment files are gitignored; secrets rotation cadence is held internally</li></ul> <h2>Emergency-change log</h2> <p>Emergency changes are recorded in a restricted administrator register backed by Firestore and audit-log events. Each record captures the date/time, summary, severity, systems affected, reason for bypassing the normal workflow, authorization timing, authorizer, implementer, verification steps, rollback plan, customer impact, evidence links, and post-hoc review status.</p> <p>A repository evidence index may be used for security reviews, but the operational register is the administrator-controlled system of record.</p> <h2>Roadmap</h2> <p>A rolling two-year product roadmap is maintained at <code>hiringcoach.ai/roadmap</code>.</p> <h2>Related</h2> <ul><li><a href="/trust/docs/sdlc">secure development lifecycle</a>: secure development practices</li><li><a href="/trust/docs/patch-management">patch management</a>: dependency/CVE SLAs</li><li><a href="/trust/docs/incident-response">incident response</a>: emergency-change post-mortems</li></ul>