Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

ci(release_workspace): add additional checks and document workflow #1175

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

ci(release_workspace): add additional checks and document workflow #1175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dc772bd
ci(release_workspace): add additional checks and document workflow
BethGriggs Aug 19, 2024
960be3f
doc: clarify plugin maintainer patch release process
BethGriggs Sep 5, 2024
7edf67c
Merge branch 'main' into poc-multiple-releases-pt-2
BethGriggs Sep 5, 2024
02c2f5e
Merge branch 'main' into poc-multiple-releases-pt-2
awanlin Oct 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions .github/workflows/release_workspace.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ jobs:
run: yarn install --immutable

- name: Fetch previous commit for release check
if: ${{ github.event.before != '' }}
run: git fetch origin '${{ github.event.before }}'

- name: Fetch the commit that triggered the workflow (used by backstage/changesets-action)
Expand All @@ -85,6 +86,7 @@ jobs:
if: inputs.force_release != true
run: node ../../scripts/ci/check-if-release.js
env:
TARGET_BRANCH: ${{ inputs.branch }}
WORKSPACE_NAME: ${{ inputs.workspace }}
COMMIT_SHA_BEFORE: '${{ github.event.before }}'

Expand Down Expand Up @@ -116,6 +118,14 @@ jobs:
NODE_OPTIONS: --max-old-space-size=4096

steps:
- name: Ensure branch name follows the 'workspace/{workspace}' pattern if not 'main'
run: |
if [ "${{ inputs.branch }}" != "main" ] && [[ "${{ inputs.branch }}" != "workspace/${{ inputs.workspace }}" ]]; then
echo "Branch name '${{ inputs.branch }}' does not follow the expected pattern 'workspace/${{ inputs.workspace }}'."
exit 1
fi
working-directory: ${{ github.workspace }}

- name: Checkout
uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4
with:
Expand Down Expand Up @@ -150,13 +160,22 @@ jobs:
- name: Build all packages
run: yarn build:all

- name: Determine npm publish tag (latest or maintenance)
id: determine-tag
run: |
if [ "${{ inputs.branch }}" = "main" ]; then
echo "tag=latest" >> $GITHUB_OUTPUT
else
echo "tag=maintenance" >> $GITHUB_OUTPUT
fi

- name: publish
run: |
yarn config set -H 'npmAuthToken' "${{secrets.NPM_TOKEN}}"
yarn workspaces foreach -v --no-private npm publish --access public --tolerate-republish
yarn workspaces foreach -v --no-private npm publish --access public --tolerate-republish --tag ${{ steps.determine-tag.outputs.tag }}
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

- name: Create tag
working-directory: ${{ github.workspace }}/scripts/ci
run: node create-tag.js
Expand Down
38 changes: 38 additions & 0 deletions docs/plugin-maintainers-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Plugin Maintainer Guide

## Table of Contents

- [Plugin Maintainer Guide](#plugin-maintainer-guide)
- [Table of Contents](#table-of-contents)
- [Maintaining and patching an older release line](#maintaining-and-patching-an-older-release-line)
- [Patching an older release](#patching-an-older-release)

## Maintaining and patching an older release line

It may be necessary to patch a prior release line of a plugin when users depend on an older, but stable version and while a newer, incompatible, major version of the plugin exists. Typically for these older releases, only major bugs and security issues will need to be remediated. Not every plugin will need this workflow.

This guide will describe the steps needed to release on an older version.

### Patching an older release

When patching an older release, follow the steps below to ensure the correct workflow is applied:

1. Request a `workspace/${workspace}` branch:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does one request a branch?

Copy link
Collaborator Author

@BethGriggs BethGriggs Oct 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can think of a few options:

  • An issue template in this repo to request the branch
  • Discord the Plugin Maintainers to request the branch
  • Universally have a maintenance branch per workspace restricted to the respective codeowners for that workspace

What do you think is best to start?

If not explained elsewhere, the reason this is an explicit step is because the workflow is coded to only release plugins from the workspace included in the branch name, and so we can set up appropriate access to that branch based on the codeowners/plugin.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if you need to be an org member to run the workflow, then you might as well ping that person at the outset to get them to create the branch so you can then later run the workflow.

An issue template would boilerplate the request and give people something to link to for the branch creation and later workflow runs too, so maybe that's worth doing.

- Ensure that a branch named `workspace/${workspace}` exists, with appropriate branch protections in place. This branch will be used for patch releases.
- The `${workspace}` should correspond to the specific plugin or component you are patching.

2. Reset the `workspace` branch:
- Reset the `workspace/${workspace}` branch to the version of the plugin you need to patch.
- You can use the autogenerated version tags from previous releases to pinpoint the prior release version to apply the patch.

3. Apply your commits:
- Apply the necessary patch fixes or security updates.
- Manually bump the version in `package.json` to reflect the new patch version (e.g., from `1.2.3` to `1.2.4`).

4. Run the release workflow:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we highlight what access you need to be able to run the workflow? This could go in a section towards the top. Pretty sure you need to be an Org Member 🤔

- Navigate to the GitHub Actions tab in your repository and manually trigger the release workflow.
- When prompted:
- Specify the `workspace` (this refers to the workspace which contains the plugin you are patching).
- Specify the `branch` you are patching. It must correspond to the workspace specified following the `workspace/${workspace}` convention.
- Select the `force release with no changesets` option.
- The workflow will run, building and releasing the patched version. A new version tag will be published which you can use as the base for future patch/maintenance releases.
Loading