Skip to content

Update release.md for release candidate releases #450

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

Closed
cdils wants to merge 2 commits into from
+183 −24
Closed

Update release.md for release candidate releases #450

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4ad98c3
Update release.md for release candidate releases
cdils Feb 10, 2026
ea37f79
Merge branch 'release_1.4.0' into issue434/update-release-doc
cdils Feb 16, 2026
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
207 changes: 183 additions & 24 deletions RELEASE.MD
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,49 @@
# Releasing a new version of FAIR Connect

## 0. Ensure adequate permissions
To perform a release of FAIR Connect, you need the following:
To perform a release of FAIR Connect, the Release Manager needs the following:
- `write` or higher permissions on the [FAIR Connect repository](https://github.com/fairpm/fair-plugin)
- `maintain` or higher permissions on the [TSC repository](https://github.com/fairpm/tsc) (this is required to post a Discussion in the Announcements category per step 7.3.)
- `maintain` or higher permissions on the [TSC repository](https://github.com/fairpm/tsc) (this is required to post a Discussion in the Announcements category per step 9.3.)

## 1. Verify milestone readiness
## 1. Branching strategy overview

FAIR Connect follows a gated release branching strategy to ensure quality and control. For the complete strategy and automation details, see [Release Branching Strategy](https://github.com/fairpm/tsc/blob/main/process/release-branching.md).

### Release branch lifecycle:
1. A `release/X.Y.Z` branch is created from `main` before the release process begins
2. All version bumps and fixes for this release happen on the `release/X.Y.Z` branch
3. The release manager merges `release/X.Y.Z` → `development` for testing and RC validation
4. Once validated, the release manager merges `release/X.Y.Z` → `main` for the production release

This document assumes the `release/X.Y.Z` branch already exists.

## 2. Release types and versioning

FAIR Connect supports two types of releases, each with distinct workflows and version naming conventions:

### Production Release
A production release represents a stable, tested version ready for general use.
- **Version format:** `MAJOR.MINOR.PATCH` (e.g., `1.2.0`)
- **Merge target:** `main` branch
- **GitHub release:** Marked as the latest release
- **Announcement:** Posted to Announcements discussion

### Release Candidate (RC)
A release candidate is a pre-release version intended for testing and validation before the final production release. Multiple RCs may be created and tested before the final release.
- **Version format:** `MAJOR.MINOR.PATCH-rcN` (e.g., `1.2.0-rc1`, `1.2.0-rc2`)
- **Merge target:** `development` branch
- **GitHub release:** Marked as a pre-release (not the latest release)
- **Announcement:** Typically not announced to production users; may be shared in Discussions for testing feedback

Use the appropriate workflow below based on which release type you are performing.

## 3. Verify milestone readiness

Before starting the release process, ensure that the milestone for the upcoming release is finalized and clear.

1. Go to the FAIR Connect [**Milestones**](https://github.com/fairpm/fair-plugin/milestones) page.

You can also access this from the repository’s main page by clicking **Issues** or **Pull requests**, then **Milestones**.
You can also access this from the repository's main page by clicking **Issues** or **Pull requests**, then **Milestones**.

2. Open the milestone corresponding to the version being released.
3. Review all issues and pull requests assigned to the milestone.
Expand All @@ -24,22 +56,133 @@ Before starting the release process, ensure that the milestone for the upcoming

Once the milestone contains no open issues or pull requests, the release is ready to proceed.

## 2. Start the release workflow
---

# Releasing a Release Candidate (RC)

Follow these steps to release an RC from the `release/X.Y.Z` branch. Multiple RCs may be created and tested before moving to the production release.

## 1. Start the release workflow

1. Go to the FAIR Connect [repository](https://github.com/fairpm/fair-plugin/actions).

2. Click the **Actions** tab.

3. In the *Actions* workflow list, select **Bump version for release**.

## 2. Configure and run the workflow

1. Click the **Run workflow** button. A workflow input panel opens.

2. Complete the following fields:

- **Use workflow from:** Select **Branch: release/X.Y.Z**
- **New version being released:** Enter the RC version using the format `X.Y.Z-rcN` (e.g., `1.2.0-rc1`, `1.2.0-rc2`)

3. Click the **Run workflow** button to start the release process.

4. Refresh the page to view workflow progress.

5. Click the running workflow to open the logs.

6. When the workflow finishes, it creates a pull request containing the version-bump changes.

## 3. Review and merge the version bump PR

1. Go to the **Pull requests** tab.

2. Open the version-bump pull request created by the release workflow.

3. Review the changes:

- Update of the version number in `plugin.php`
- Update the `VERSION` constant in `plugin.php`

4. Confirm that the changes are correct.

5. After review and approval, merge the PR to the `release/X.Y.Z` branch.

6. Go to the **Actions** tab to verify that workflow processing is complete.

7. Continue to the next step once all workflows finish.

## 4. Merge release branch to development

The `release/X.Y.Z` branch must be merged to `development` for testing and validation.

1. In the repository, create a pull request to merge `release/X.Y.Z` → `development`
2. For the PR title, use: `release: merge release/X.Y.Z into development for RC testing`
3. Ensure all checks pass and obtain required reviews per branch protection rules
4. Merge the PR to `development`
5. Continue to the next step once the merge is complete

## 5. Create a new release on GitHub

1. From the repository's main page, click the **Releases** link — or go directly to the [Releases page](https://github.com/fairpm/fair-plugin/releases).

2. Click the **Draft a new release** button.

3. In the **Select tag** field:
- Select the tag that matches the version you just bumped to (e.g., `1.2.0-rc1`).
- Create a new tag if it does not appear in the dropdown.
- **Target branch:** Select `development`

4. In the **Release title** field, enter a title for the release (e.g., `1.2.0-rc1`).

5. Under **Release notes**:
- Leave the **Describe this release** field empty or add minimal testing instructions (release notes will be generated when the final production release is created).
- Check **Set as a pre-release** to mark this as a release candidate.

6. Click the **Save draft** button.

## 6. Finalize and publish the release

1. Return to the **Draft Release** page, if not already there.

2. Release-specific settings:
- Do NOT check **Set as the latest release** (already marked as pre-release from step 5).
- Optionally check **Create a discussion for this release** if you want to notify testers; if checked, you may choose a different category (e.g., General) instead of Announcements.

3. In a new browser tab, go to the repository's **Actions** tab and confirm all workflows have completed.

4. Return to the **Draft Release** page and click **Publish release**. This initiates the remaining release workflows.

5. Verify the release:
- Visit the [Releases page](https://github.com/fairpm/fair-plugin/releases) to confirm RC is tagged as pre-release.
- Notify relevant testers to validate the RC version.

## 7. Next steps

### If additional testing iterations are needed:
1. Continue making fixes on the `release/X.Y.Z` branch
2. Merge fixes back to `development`
3. Repeat steps 2-6 for the next RC (e.g., `1.2.0-rc2`)

### If the RC is validated and ready for production:
Proceed to the **Production Release** workflow below to merge `development` → `main` for the final release.

---

# Releasing a Production Release

Follow these steps to release the production version from `main` after the RC(s) have been validated.

## 1. Start the release workflow

1. Go to the FAIR Connect [repository](https://github.com/fairpm/fair-plugin/actions).

2. Click the **Actions** tab.

3. In the *Actions* workflow list, select **Bump version for release**.

## 3. Configure and run the workflow
## 2. Configure and run the workflow

1. Click the **Run workflow** button. A workflow input panel opens.

2. Complete the following fields:

- **Use workflow from:** Select **Branch: main** (default).
- **New version being released:** Enter the release version number (e.g., `1.0.0`). FAIR Connect uses semantic versioning (`MAJOR.MINOR.PATCH`).
- **Use workflow from:** Select **Branch: main**
- **New version being released:** Enter the production version using semantic versioning format (e.g., `1.2.0`)

3. Click the **Run workflow** button to start the release process.

Expand All @@ -49,7 +192,7 @@ Once the milestone contains no open issues or pull requests, the release is read

6. When the workflow finishes, it creates a pull request containing the version-bump changes.

## 4. Review and merge the version bump PR
## 3. Review and merge the version bump PR

1. Go to the **Pull requests** tab.

Expand All @@ -68,29 +211,38 @@ Once the milestone contains no open issues or pull requests, the release is read

7. Continue to the next step once all workflows finish.

## 4. Merge development into main

The `development` branch contains the tested and validated RC(s) and must be merged to `main` for the production release.

1. In the repository, create a pull request to merge `development` → `main`
2. For the PR title, use: `release: merge development into main for production release`
3. Ensure all checks pass and obtain required reviews per branch protection rules
4. Merge the PR to `main`
5. Continue to the next step once the merge is complete

## 5. Create a new release on GitHub

1. From the repository’s main page, click the **Releases** link — or go directly to the [Releases page](https://github.com/fairpm/fair-plugin/releases).
1. From the repository's main page, click the **Releases** link — or go directly to the [Releases page](https://github.com/fairpm/fair-plugin/releases).

2. Click the **Draft a new release** button.

3. In the **Select tag** field:
- Select the tag that matches the version you just bumped to (e.g., `1.2.0`).
- Create a new tag if it does not appear in the dropdown.
- **Target branch:** Select `main`

4. In the **Release title** field, enter a title for the release (e.g., `1.2.0`).

5. Under **Release notes**:
- Leave **Previous tag** set to `Auto`.
- Click **Generate release notes**.
- Review and edit the generated notes as needed.
- Click the **Save draft** button.
- You can add additional information directly in the **Describe this release** field if needed. If a teammate is preparing a release post for FAIR.pm, coordinate with them to include any relevant details.

> [!TIP]
> You can add additional information directly in the **Describe this release** field.
> If a teammate is preparing a release post for FAIR.pm, coordinate with them to include any relevant details.
6. Click the **Save draft** button.

## 6. Update the changelog before publishing the GitHub release
## 6. Update the changelog

1. In a new browser tab, open [`CHANGELOG.md`](/CHANGELOG.md).

Expand All @@ -107,20 +259,27 @@ Once the milestone contains no open issues or pull requests, the release is read

6. Review, approve, and merge the pull request.


## 7. Finalize and publish the release

1. Return to the **Draft Release** page.

2. Check **Set as the latest release**.
2. Release-specific settings:
- Check **Set as the latest release**.
- Check **Create a discussion for this release** and choose the **Announcements** category.

3. In a new browser tab, go to the repository's **Actions** tab and confirm all workflows have completed.

3. Check **Create a discussion for this release** and choose the **Announcements** category.
4. Return to the **Draft Release** page and click **Publish release**. This initiates the remaining release workflows.

4. In a new browser tab, go to the repository’s **Actions** tab and confirm all workflows have completed.
5. Verify the release:
- Visit the [Releases page](https://github.com/fairpm/fair-plugin/releases) to confirm latest release.
- Check any site using FAIR Connect to ensure the new version is available.
- Verify the updated version number in the API response. (Example URL to check: https://api.fair.pm/git-updater/v1/update-api/?slug=fair-plugin)

5. Return to the **Draft Release** page and click **Publish release**. This initiates the remaining release workflows.
## 8. Cleanup

6. Verify the release:
- Visit the [Releases page](https://github.com/fairpm/fair-plugin/releases) to confirm latest release.
- Check any site using FAIR Connect to ensure the new version is available.
- Verify the updated version number in the API response. (Example URL to check: https://api.fair.pm/git-updater/v1/update-api/?slug=fair-plugin)
1. In the repository, create a pull request to merge `release/X.Y.Z` → `main` (if not already merged as part of the development merge)
2. For the PR title, use: `release: merge release/X.Y.Z into main`
3. Ensure all checks pass and obtain required reviews per branch protection rules
4. Merge the PR to `main`
5. Delete the `release/X.Y.Z` branch to keep the repository clean