You are here: Home » pub » Introduction to Development » Releasing

Releasing

Table of Contents

Releasing

Warring
The content of this page is still in progress and needs some tweaking.

Creating a Standard Release

  • Ensure a branch exists for the version family (for 2022.12.2 the branch would be version-2022.12)
  • Merge all the commits that should be released on the version branch
  • If backporting commits to a non-current version branch, cherry-pick the commits.
  • Push the branch, which will run the CI pipeline to make sure all tests pass
  • Create/update the release notes

For initial releases:

  • Copy docs/platform/unicis-platform-changelog/_template.md to docs/platform/unicis-platform-changelog/v2022.12.md and replace xxxx.x with the version that is being released
  • Fill in the section of Breaking changes and New features, or remove the headers if there’s nothing applicable
  • Run git log --pretty=format:'- %s' version/2022.11.3...version-2022.12, where version/2022.11.3 is the tag of the previous stable release. This will output a list of all commits since the previous release.
  • Paste the list of commits since the previous release under the Minor changes/fixes section.
  • Run make gen-changelog and use the contents of changelog.md. Remove merged PRs from bumped dependencies unless they fix security issues or are otherwise notable. Remove merged PRs with the website/ prefix.
  • Sort the list of commits alphabetically and remove all commits that have little importance, like dependency updates and linting fixes
  • Run make gen-diff and copy the contents of diff.md under API Changes
  • Update website/sidebars.js to include the new release notes, and move the oldest release into the Previous versions category.
  • If the release notes are created in advance without a fixed date for the release, only add them to the sidebar once the release is published.
  • Run make website

For subsequent releases:

  • Paste the list of commits since the previous release into docs/platform/unicis-platform-changelog/v2022.12.md, creating a new section called ## Fixed in 2022.12.2 underneath the Minor changes/fixes section
  • Run make gen-changelog and use the contents of changelog.md. Remove merged PRs from bumped dependencies unless they fix security issues or are otherwise notable. Remove merged PRs with the website/ prefix.
  • Run make gen-diff and copy the contents of diff.md under API Changes, replacing the previous changes
  • Run make website
  • Run bumpversion on the version branch with the new version (i.e. bumpversion --new-version 2022.12.2 minor --verbose)
  • Push the tag and commit
  • A GitHub actions workflow will start to run a last test in container images and create a draft release on GitHub
  • Edit the draft GitHub release
  • Make sure the title is formatted Release 2022.12.0
  • Add the following to the release notes
  • See https://www.unicis.tech/docs/platform/unicis-platform-changelog
  • Or if creating a subsequent release
  • See https://www.unicis.tech/docs/platform/unicis-platform-changelog
  • Auto-generate the full release notes using the GitHub Generate Release Notes feature

Preparing a Security Release

  • Create a draft GitHub Security advisory

Template

  • Request a CVE via the draft advisory
  • If possible, add the original reporter in the advisory
  • Implement a fix on a local branch security/CVE-...
  • The fix must include unit tests to ensure the issue can’t happen again in the future
  • Update the release notes as specified above, making sure to address the CVE being fixed
  • Create a new file /website/docs/security/CVE-....md with the same structure as the GitHub advisory
  • Include the new file in the /website/sidebars.js
  • Check with the original reporter that the fix works as intended
  • Wait for GitHub to assign a CVE
  • Announce the release of the vulnerability via Mailing list and discord

Mailing list template” close

Discord template

Creating a Security Release

  • On the date specified in the announcement, push the local security/CVE-2022-xxxxx branch into a PR, and squash merge it if the pipeline passes
  • If the fix made any changes to the API schema, merge the PR to update the web API client
  • Cherry-pick the merge commit onto the version branch
  • If the fix made any changes to the API schema, manually install the latest version of the API client in /web
  • Resume the instructions above, starting with the bumpversion step
  • After the release has been published, update the Discord announcement and send another mail to the mailing list to point to the new releases

Mailing list template

Discord template

This guide includes the steps required for creating both standard and security releases, with specific references and links for the Unicis Platform Business and Community Editions.