When releasing new software versions, there is a formal set of tasks that need to be done in order to make sure all bases of a release are covered. This article will outline the general actions needed to update and release a conventional application + frontend stack, but can be adapted for other kinds of formal software releases. For the most part, follow this guide sequentially and you should be able to perform a formal software release.

Before starting a release, make sure all checkboxes have been procedurally checked off first and that the team agrees it is ready to be published.

• Check all relevant Pull Requests in the repository are closed
• Check all related JIRA tickets are closed. There should not be any more open tickets remaining in the backlog version filter.
• Update the respective Product Roadmap on the wiki to check off all remaining undone features. Work with the Product Owner and Technical Leads to ensure the roadmap contents are accurate.

The following focuses on updating all software dependencies for security patches and other functionalities.

• Create a new branch called chore/release. (git checkout -b chore/release).

For each software subdirectory such as /app and /frontend, do the following:

• Perform an NPM security and dependency update via npx npm-check -u.
• For every package listed, check their respective changelogs.
  • Look for any mentions of breaking changes, dependencies, or behavioral changes that could potentially impact the application.
• Select the non-impactful updates by pressing space.
  • Skip any dependencies that you suspect may have an adverse impact on the application for now; we will revisit that in Update Impact Assessment.
• Apply the changes. If there are npm audit warnings, evaluate and fix them as necessary. It is "usually" safe to run npm audit fix as this generally updates any lagging peer dependencies only; however you NEVER want to run the --force variant as this can destructively override any specific version locks we have.
• Test the application with npm run test
  • If this is an API, perform a quick happy-path regression test to ensure things are still functioning.
  • If this is a frontend, spin up the application locally and ensure that the app appears to behave properly via regression testing.
    • For even further validation, run npm run build to statically build the application and run it with npm run start to ensure that a statically built frontend still behaves as intended (this is what actually gets run on Openshift).
• If verification succeeded, git stage all the dependency updates.

• If there are packages you skipped from earlier, you will now test for them here.

• Update one package at a time via npx npm-check -u and verify that the update does not adversely impact the application.

  • If it seems fine, add the changes to your staged changes.
  • If the package update breaks certain functionality, perform attempt to isolate and resolve the issue.
    • If it is a quick fix, implement the necessary changes and stage.
    • If it appears more involved (like dependency chain chaos or something that would take a non-trivial amount of time to resolve), bring it up to the team and decide next steps via triage (temporarily hard-peg to an older version, replace dependency with alternative, or etc). Generate new JIRA tickets when/where appropriate if deferring.
      • If we are temporarily pegging to a specific version, update the package.json entry for the affected dependency by prefixing the version number with an ~ (e.g. "primevue": "~3.34.1"). Normally NPM will use a ^ which means allow any minor and patch releases; however we use ~ to signal a more precise restriction which means allow any patch releases only. NPM range notation may alternatively be used if we know that the dependency only works for a certain version range (e.g. "primevue": ">=3.34.0 <3.34.1").

• Once all dependencies have been resolved (via update or deferral peg), ensure that your commit has updated the correct package.json and package-lock.json files as expected.

• Commit the changes with the following commit message:

  Routine NPM dependency updates

  If there are dependency pegs or other noteworthy changes, ensure that the commit message also includes a description body explaining the rationale of the changes, and any relevant links if needed.

Core deployment infrastructure must also be updated as a part of the release process, as the infrastructure the software runs on can have a major impact on security and software reliability.

• Visit https://nodejs.org/en and note down the latest current LTS version. We always follow the stable Long-Term Support channel for Node in order to keep up to date with security patching and minimizing potential impacts from new feature development from Node upstream.
• On our Dockerfile, if the image is alpine-based, update the image tag to point to the noted down LTS release version (e.g. docker.io/node:20.11.1-alpine).
• In the rare event the docker image fails to build or run after the version update, consult with the Technical Lead for next steps and risk impact assessment.

This section requires that you have the helm-docs tool installed. If you do not have this tool already, visit https://github.com/norwoodj/helm-docs#installation and follow their installation guide depending on the OS you are on.

• Open the Chart.yaml file which is typically found under /charts/<appname> and update the following attributes:

  • version should get a patch bump (e.g. 0.0.15 -> 0.0.16).
  • appVersion should get the actual application version change (e.g. 0.4.0 -> 0.5.0).

• In a unix terminal, cd to the /charts/<appname> directory wherever the Chart.yaml file is at.

• Run helm-docs. This will automatically update the README.md that is in the helm chart.

  • This README is always programatically generated from our helm chart - you should NOT be updating this README manually without a good reason.

• Commit the changes with the following commit message:

  Routine Dockerfile and Helm chart version bumps

In addition to updating the infrastructure code, the Devops pipeline code responsible for facilitating smooth continuous delivery needs to also be updated periodically. Ensure that as a part of the release cycle that dependent github actions are updated to the latest versions where appropriate. This is important in order to ensure we do not continue to run potentially vulnerable code in our pipelines.

• Update the SECURITY.md file to support the new application version, and signal deprecation of support to older versions.
• Check for any other README.md files in lower directories and update them as necessary.
• Amend the previous infrastructure commit if necessary.
• On the root Github page for your application, click the Releases header on the right side-pane. Then click Draft a new release
• Under Choose a tag, type in the new version. This MUST be in semver (e.g. v0.5.0). As this tag does not exist yet, click Create new tag: <your tag> on publish to set it.
• Release title field should ONLY be the semver (e.g. v0.5.0).
• Visit the Product Roadmap for your application, click edit, and verbatim copy the version header, title, and checkbox lists for the appropriate version to the Describe this release field.
  • Remove the [x] values from the bullet points.
  • Click Generate release notes to automatically compile the PR and changelogs from git history
• Double check for markdown formatting glitches in the Preview tab and fix accordingly. Reference previous releases for style and formatting if necessary.
• Click Save draft and let the Tech Lead or fellow developers review before publishing.
• If everything is good, click Publish release. 🎉
• Announce the version release in Discord and any other relevant communication channels as necessary.

If you made it this far, congratulations you have successfully performed a formal version release. 🎉