Release Process

The following process describes the steps of releasing a new version of the issue-labeler. The steps begin at the stage of the main branch containing what is desired to be marked as a new version of the workflows. The release process requires a few iterations can capturing multiple commit SHA values to ensure each release is fully pinned to a consistent state through each layer of the architecture.

Capture the SHA for the commit to be staged as a release

This will be referred to as SHA A below. In the example, SHA A is d74b8e18f41673790be3d0ca87296a49e81ac19a.

Edit all of the /.github/worklows files that use actions/checkout

Update the ref to the SHA A in each usage of actions/checkout. This will snap the reusable workflows that consume the code from the repository to the desired commit.

      - name: "Check out the 'dotnet/issue-labeler' repo"
        uses: actions/checkout@v4
        with:
          repository: dotnet/issue-labeler
          ref: d74b8e18f41673790be3d0ca87296a49e81ac19a# Staging v1.0.1

The following files need to be edited in this step.

1. build-predictor.yml
2. download-issues.yml
3. download-pulls.yml
4. test-issues.yml
5. test-pulls.yml
6. train-issues.yml
7. train-pulls.yml

Merge those file updates and capture this new commit SHA. This will be referred to as SHA B below. See Staging the v1.0.1 release (dotnet/issue-labeler#89) for an example of this release process step. In this example, SHA B is 68a3df3b6444ec3e2a37af4d5e2569df1d45201d.

Update the Train workflow

The train.yml workflow composes the above workflows, providing a single workflow. We need to update all of the references it has to SHA B. There should be 7 matches in the file, one for each of the 7 workflows updated above.

uses: dotnet/issue-labeler/.github/workflows/build-predictor.yml@68a3df3b6444ec3e2a37af4d5e2569df1d45201d # Staging v1.0.1
...
uses: dotnet/issue-labeler/.github/workflows/download-issues.yml@68a3df3b6444ec3e2a37af4d5e2569df1d45201d # Staging v1.0.1
...
uses: dotnet/issue-labeler/.github/workflows/train-issues.yml@68a3df3b6444ec3e2a37af4d5e2569df1d45201d # Staging v1.0.1
...
uses: dotnet/issue-labeler/.github/workflows/test-issues.yml@68a3df3b6444ec3e2a37af4d5e2569df1d45201d # Staging v1.0.1
...
uses: dotnet/issue-labeler/.github/workflows/download-pulls.yml@68a3df3b6444ec3e2a37af4d5e2569df1d45201d # Staging v1.0.1
...
uses: dotnet/issue-labeler/.github/workflows/train-pulls.yml@68a3df3b6444ec3e2a37af4d5e2569df1d45201d # Staging v1.0.1
...
uses: dotnet/issue-labeler/.github/workflows/test-pulls.yml@68a3df3b6444ec3e2a37af4d5e2569df1d45201d # Staging v1.0.1

Merge the update to train.yml and capture this new commit SHA. This will be referred to as SHA C below. See Staging the v1.0.1 release (step 2) (dotnet/issue-labeler#90) for an example of this release process step. In this example, SHA C is f0c098669828a134c0313adf3f58c1909e555d86.

Create the Release

This point, everything consumed by onboarded repositories has been updated, and the Release can be created. After the release is created, the issue-labeler repository itself will be updated to reference the new release using the same process other repositories use to update.

Navigate to the Releases · dotnet/issue-labeler page and click Draft a new release.

• Choose a tag
  • Type the new version number tag name to create the tag for this release. In this example, we're creating v1.0.1.
  • Click + Create new tag: vX.Y.Z on publish
• Target
  • Select the Recent Commits* tab
  • Click the commit matching SHA C above; the short SHA will be shown
• Release Title
  • Enter a release title in the following format: vX.Y.Z - yyyy-MM-dd - Description
• Describe this release
  • Provide a description that helps consumers understand the value of upgrading to this release
  • Consider using the Generate release notes button to list changes made since the last release
• Set as the latest release
  • Leave this box checked

Click Publish release to create the tag and publish the release details. Note that publishing a new release does not automatically result in any consuming repositories using the new release. Onboarded repositories pin to the commit SHA associated with the release rather than using tags, so consumers must upgrade to the new release. This is also true for the issue-labeler repository's own use of issue-labeler.

Workflows not updated

During the process of releasing a new version of issue-labeler, there are several workflow files that did not get updated. There are two categories for these workflows, first being workflows that operate purely off the GitHub Action Cache without consuming code from the issue-labeler repository; second being the issue-labeler's own usage of issue-labeler.

Workflows operating off the GitHub Action Cache

The following reusable workflows are part of the issue-labeler implementation, but they do not contain any commit SHA references that need to be updated as part of the release process.

1. cache-retention.yml
2. predict-issues.yml
3. predict-pulls.yml
4. promote-issues.yml
5. promote-pulls.yml

Consuming workflows

The following workflows are part of the repository's consumption of issue-labeler, and they will be updated to reference the new version in the same manner as other repositories that use issue-labeler. Notice that all of these workflows are prefixed with labeler- to distinguish them from the workflows that are part of the implementation. Other repositories also use the labeler- prefix for these workflows to keep them grouped together.

1. labeler-build-predictor.yml
2. labeler-cache-retention.yml
3. labeler-predict-issues.yml
4. labeler-predict-pulls.yml
5. labeler-promote.yml
6. labeler-train.yml