Release Process

Overview

Releases are promoted via a Pull Request from main to production. Any work that is not ready for production must be hidden behind a feature flag (gated). GitHub Actions automatically builds, generates sitemaps, runs tests and deploys.

main ──▶ (PR) ──▶ production ──▶ deploy

Step-by-Step : Release Flow

1. Prepare main

1. Merge all feature branches into main via PR.
2. Review changes:
   • Confirm any incomplete features are behind feature flags.
   • Ensure tests and typechecks pass locally.

---

2. Open a release PR (main → production)

1. Create a PR with:
   • Base: production
   • Compare: main
2. 🚨 Merge using “Create a merge commit” (do not squash-merge), so we preserve individual conventional commits (this will be used by the standard-version package to create a detailed changelog).

---

3. Github Actions: Build steps

The release pipeline automatically runs the following steps when content is merged into the production branch.

• yarn generate-footer-content Generates release information for portal page footer.

• yarn generate-metadata-completeness-fields Generates metadata completeness score fields based on NDE API specifications.

• yarn generate-dataset-sitemaps Generates sitemaps for datasets of approved sources.

• yarn build (uses .env.production) Builds the Next.js application.

• yarn test Runs the test suite

• next-sitemap (via postbuild) Generates portal specific sitemaps

Deployment is then performed via AWS (S3 + CloudFront). At this point, the code is deployed to production.

---

4. Create the release on production (optional)

After merging the PR and deploying, create a version tag.

Locally:

git checkout production
yarn release         # or release:patch/minor/major
git push --follow-tags

This updates the CHANGELOG.md and creates a semantic version tag based on commit history.

standard-version will:

• Look at commits on prod since the last tag

• Update package.json

• Update CHANGELOG.md

• Create a new commit and tag (e.g. v1.8.0)

Notes & conventions

Do not use "Squash and merge" for PRs into prod. standard-version relies on individual conventional commits to generate an accurate changelog.

It’s fine to use squash merges into main if you want, as long as the final squashed commit message is a valid Conventional Commit.

If you ever need to skip tests(e.g. include skip test in the commit message), but try to avoid this for release-related commits.

Potential Improvements

• Use a github action to create the release based on pushes to the production branch
• Only allow merge commits (no squash or rebased) on the production branch (in gh settings)
• Use github action to generate sitemaps on a regular(weekly) basis and remove sitemap generation command on build.