Release Process

This document covers how CPR frontend releases are versioned, prepared, executed, and verified.

Versioning Strategy

The CPR frontend uses the version field in package.json as the single source of truth. This version is automatically exposed to the application at runtime:

// nuxt.config.ts
runtimeConfig: {
  public: {
    appVersion: process.env.npm_package_version || '1.0.0',
  },
},

The app version is accessible anywhere via useRuntimeConfig().public.appVersion.

Semantic Versioning

Follow semver -- MAJOR.MINOR.PATCH:

Increment	When	Example
MAJOR	Breaking changes to the UI or workflows that affect end users	1.0.0 -> 2.0.0
MINOR	New features, new modules (e.g., a new CRUD module)	1.0.0 -> 1.1.0
PATCH	Bug fixes, small UI corrections, dependency patches	1.0.0 -> 1.0.1

Pre-Release Checklist

Complete every item before proceeding with a release:

Code Quality

• [ ] All feature branches have been merged to master
• [ ] npm run lint passes with no errors
• [ ] npm run format passes with no errors
• [ ] No TypeScript compilation errors
• [ ] All known critical bugs are resolved

Testing

• [ ] Manual testing of all changed features
• [ ] Cross-browser testing (Chrome, Firefox, Safari at minimum)
• [ ] Test login/logout flow
• [ ] Test patient record operations (create, read, update)
• [ ] Test pharmacy module if changed
• [ ] Test surgery schedule if changed
• [ ] Verify error handling shows user-friendly messages

Build Verification

• [ ] npm run build completes without errors
• [ ] npm run preview -- verify the production build works locally
• [ ] Confirm console.log statements are stripped in the preview build
• [ ] Confirm Sentry is capturing errors correctly

Security

• [ ] No hardcoded API keys or credentials in the codebase
• [ ] No patient data exposed in logs or error messages
• [ ] sendDefaultPii remains false in Sentry config
• [ ] .env files are listed in .gitignore

Release Steps

1. Update the Version

On master, bump the version in package.json:

# For a patch release
npm version patch --no-git-tag-version

# For a minor release
npm version minor --no-git-tag-version

# For a major release
npm version major --no-git-tag-version

The --no-git-tag-version flag prevents npm from auto-committing and tagging, giving you control over the commit message.

2. Commit the Version Bump

git add package.json package-lock.json
git commit -m "chore: bump version to X.Y.Z"

3. Tag the Release

git tag vX.Y.Z

4. Push

git push origin master
git push origin vX.Y.Z

5. Build and Deploy

npm run build

Deploy the .output directory to the production environment. Ensure the following environment variables are set in the deployment target:

• API_URL -- production backend API URL
• SENTRY_DSN -- production Sentry DSN
• Sentry auth token for source map uploads

6. Create a GitHub Release

Create a release on GitHub from the tag with release notes summarizing the changes:

gh release create vX.Y.Z --title "vX.Y.Z" --notes "Release notes here"

Include:

• New features added
• Bugs fixed
• Breaking changes (if any)
• Any required backend changes or migrations

Post-Release Verification

After deploying to production:

Immediate Checks (within 15 minutes)

• [ ] Application loads without errors
• [ ] Login flow works
• [ ] Verify the app version matches the release (check runtimeConfig)
• [ ] Check the browser console -- no JavaScript errors
• [ ] Check Sentry dashboard -- no new error spikes
• [ ] Verify source maps are uploaded (Sentry stack traces show readable code)

Functional Checks (within 1 hour)

• [ ] Navigate through all major sections (dashboard, patients, pharmacy, queue, configuration)
• [ ] Perform a test patient record lookup
• [ ] Verify API communication is working (check network tab)
• [ ] Confirm session/auth token handling works correctly

Monitoring (24 hours)

• [ ] Monitor Sentry for elevated error rates
• [ ] Check Sentry Session Replay for user-facing issues
• [ ] Gather early feedback from clinical staff using the system

Rollback Procedures

If critical issues are discovered after a release:

Quick Rollback

If the previous version's build artifacts are still available, redeploy the previous version immediately. No code changes needed.

Code Rollback

If you need to revert to the previous version in the codebase:

1. Identify the last good release tag:

   git tag --list 'v*' --sort=-version:refname

2. Create a hotfix branch from the last good tag:

   git checkout -b hotfix/rollback-vX.Y.Z vX.Y.Z-1

   Or revert the problematic commits on master:

   git checkout master
   git revert <commit-hash>

3. Rebuild and redeploy:

   npm install
   npm run build

4. Communicate the rollback to the team and document what went wrong.

Hotfix Process

For targeted fixes without rolling back the entire release:

1. Create a hotfix/ branch from master.
2. Apply the minimal fix.
3. Run full lint and format checks.
4. Open a PR, get a review, and merge.
5. Follow the release steps above with a PATCH version bump.
6. Deploy immediately.

Release History

Track releases using Git tags and GitHub Releases. To view the release history:

# List all release tags
git tag --list 'v*' --sort=-version:refname

# View details of a specific release
git show vX.Y.Z

# Compare two releases
git diff vX.Y.Z..vA.B.C