Skip to content

CF Deployment Release

Jochen Ehret edited this page May 3, 2023 · 11 revisions

Brief

The goal of this guide is to help you create a new CF-Depolyment public release. Please free to suggest changes based on your experience with the guide.

CF-Deployment

CF-Deployment contains a canonical BOSH deployment manifest for deploying the Cloud Foundry Application Runtime by relying individual component releases. More info here CF-Deployment Repo.

Release Process

Component teams (aka feature teams) make changes to either the main manifest file or feature manifest files (also called ops file). Component teams submit PRs, which are reviewed by CF-D Approvers. Once the changes are merged, it is run through CF-D pipeline. Once they are successful, they become eligible for a release.

💡 Each change is pushed to top of the release-candidate branch

Release cadence

Releases are currently published on a best-effort cadence.

Overview

After completing these steps, you will have the following:

  1. A published release note with version #.
  2. Main tagged with release version #.

👉 Please ensure you have full access to CF-Deployment repository. If not, please check with the team anchor.

Step 1

In this step we will check if we have new changes to release.

  1. Goto CF-Deployment releases repo and click on Draft New Release.
  2. In a separate tab, goto the release-notes-template job in the CF-Deployment concourse pipeline.
  3. Click on generate-cf-deployment-release-notes-template tile (also called task), which should expand and print out a release note template. See screenshot below.
  4. Select and copy everything from line that starts with ## Notices to the bottom of the screen into the Description field of the release form that we opened in the first step. We will make edits to the description field through the guide.
  5. Leave the Tag version and Release Title fields empty. We will fill them in the last step. Click on Save Draft (and NOT Publish release. we will publish in the last step).

💡 The task release-notes-template looks at the commit history and prints out a markdown version all the changes that made it through to release-candidate e.g. new ops files or updated ops files, stemcell bumps etc. Nice, huh!

Step 2

  1. Goto compare main to release view. The goal is to review the new commits in release-candidate that will be merged into main.

Look for PRs that change cf-deployment.yml and ops files changes.

Special note on commits

Most commits are associated with a PR, which contain detailed information from the PR author such as what is the change, why the change was made and most importantly how they want it to be described in the release note e.g. PR.

  1. Read through each commit, find out their corresponding PRs and try to summarize the changes in the release notes. It is critical that we highlight changes to ops files.

⚠️ Step 2.1 is to only view the differences and not actually create a PR in GitHub. Our jobs will automatically do the merge and tagging.

Step 3

In this step, we will decide on the type of version change. More details on what we consider major, minor and patch changes are here.

Special note on versioning

Please read semantic versioning if you're aren't familiar with semantic versioning. A semantic version includes 3 parts - major.minor.patch e.g. 2.1.0. If the new changes aren't compatible with previous versions, then we bump the major version e.g. 2.1.0 => 3.0.0. If the new changes are compatible with the previous versions, then we bump the minor version only e.g. 2.1.0 => 2.2.0. We don't usually bump patch versions.

Examples of breaking changes:

Listed below are scenarios that are considered as a breaking change. Review each commit/PR against the list.

  • Changed name of a job or instance group,
  • Moved a job to a different instance group,
  • Deleted a job or instance group,
  • Changed the name of a credential,
  • Requires out-of-band manual intervention on the part of the operator,
  • Removed Ops-file (e.g. from ./operations/ or ./operations/experimental folders).
Commits Version change Next step
Have one or more breaking changes Increments major version e.g.<major+1>.0.0 Follow Major Release section in Step 4
do not have breaking changes Increments minor version e.g.<major>.<minor+1>.0 Follow Minor Release section in Step 4

Step 4

In this step we will assign a new version # to the release.

Major Release

If there are breaking changes, then,

  1. Goto CF-D concourse task.
  2. Click on + on the top right and watch the build execute.
  3. Once successfully completed, note down the version # it prints out e.g. 7.0.0 (see screen shot below).
  4. For a major release of cf-deployment, we should also cut a new major release of CATs. Use the CATs pipeline to publish a new release.

⚠️ Major and minor release are mutually exclusive. So if you have completed a major version release, then ignore the Minor Release section below.

Minor Release

If there are no breaking changes, then

  1. Goto CF-D concourse task.
  2. Click on + on the top right and watch the build execute.
  3. Once successfully completed, note down the version # it prints out e.g. 6.8.0.

Step 5

In this step, we will finally publish the release note.

  1. Goto releases section of the CF-Deployment repo. You should see your draft release note that was created in Step 1.

  2. Select the version from Step 4 in the Choose a tag dropdown, and enter that version into Release title, prefixed with a v in both cases.

  3. Finally, click on the Publish Release button.

  4. Post a notice in #cf-deployment in the Cloud Foundry Slack workspace. Use the message below to get started and feel free to use emojis!!

      CF-Deployment vX has been released.
      Please refer to the release notes for breaking changes:
      https://github.com/cloudfoundry/cf-deployment/releases/tag/vX.0.0
    

Congrats on your release! Go get a cronut with caramel topping!!!

Resources used in this guide