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.

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

110036: add workflows and readme for publishing releases #4

Merged
merged 6 commits into from
Feb 4, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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: 23 additions & 0 deletions .github/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Release notes template (https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)

changelog:
categories:
- title: Breaking Changes 🚧
labels:
# Semver-Major
- breaking change
- title: New Features ✨
labels:
# Semver-Minor
- enhancement
- title: Bug Fixes 🐛
labels:
# Semver-Patch
- bugfix
- title: Other Changes 📦
labels:
- "*"
exclude:
labels:
- chore
- version bump
21 changes: 21 additions & 0 deletions .github/workflows/label-checker.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
name: Label Checker

on:
pull_request:
types:
- opened
- synchronize
- reopened
- labeled
- unlabeled

jobs:
check_labels:
name: Check labels
runs-on: ubuntu-latest
steps:
- uses: docker://agilepathway/pull-request-label-checker:latest
with:
# At least one of the labels listed below must be present on the PR for the check to pass
any_of: breaking change,enhancement,bugfix,version bump,release,chore,documentation
repo_token: ${{ secrets.GITHUB_TOKEN }}
23 changes: 23 additions & 0 deletions .github/workflows/publish-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
name: Publish Release

on:
push:
tags:
- v[0-9]+.[0-9]+.[0-9]+

permissions:
contents: write

jobs:
publish:
runs-on: ubuntu-latest

steps:
- name: Create release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh release create "${{ github.ref_name }}" \
--repo="$GITHUB_REPOSITORY" \
--title="${{ github.ref_name }}" \
--generate-notes
55 changes: 55 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Release

This file describes the process for publishing a new version of the gem as a GitHub release.

Releases are managed through the [GitHub Releases](https://github.com/dchbx/event_source/releases) page.

Release names follow the [Semantic Versioning](https://semver.org/) standard.

Follow the steps below to package and release a new version of the gem.

## Major/Minor release
### Prepare the release
1. Checkout the main branch and pull the latest changes.
2. Create and checkout a branch - avoid naming the branch solely after proposed release number - something like 'rm12313453_v1.0.0._update_gemspec' might be ideal.
3. Update the version number in the `lib/<project>/version.rb` file. Note the [correct format](https://guides.rubygems.org/specification-reference/#version); only digits and dots are allowed. Do not include a `v` prefix.
4. Update the `Gemfile.lock` file:
- `bundle update --patch --conservative event_source` will generally reduce dependency bumps. Typically, other effects in the lockfile beyond the gem itself being bumped should be discarded.
- See bundler documentation for detailed information on how this [command](https://bundler.io/v2.5/man/bundle-update.1.html) behaves.
5. Commit the changes with a message like `bump version to v1.0.0`.
6. Push the branch and raise a pull request against the main branch. The pull request title should follow the format: `bump version to v1.0.0`. Be sure to label the pull request with the `version-bump` label.

### Publishing the Release
1. Once the pull request is approved and merged, checkout the main branch and pull the latest changes.
2. Create a new release branch in the pattern of `1.0.x-release`.
- Note: `x` is literal, to aid reuse of same branch for minor bugfixes.
3. Create a new annotated tag with the version number, e.g., `git tag -as v1.0.0 -m "v1.0.0"`.
- IMPORTANT: make sure the tag abides by the format `vX.Y.Z` where `X`, `Y`, and `Z` are integers. It is important that the tag name has a different format than any branch name to avoid confusion with Bundler.
4. Push the tag to the remote repository, e.g., `git push origin refs/tags/v1.0.0`.
- Avoid `git push --tags`, to not accidentally push random assorted local tags.
5. GitHub Actions will automatically create a new release on the [GitHub Releases](https://github.com/dchbx/event_source/releases) page with release notes. Confirm that the release was successfully published there and that all intended commits are included in the release.

## Patch/Bugfix release
### Prepare the release
1. Fix bug in the main branch, via normal PR process.

For any release that has the bug:
2. Create a temp branch off any live release branch that has the bug - pick a name that won't conflict with another branch or tag, as with Major/Minor step 2.
- Using a branch, which is then PR’d, ensures traceability and inclusion of an item in the generated release notes.
3. Cherry-pick the fix commits to the temp branch.
4. Update the gem `version.rb` file and `Gemfile.lock` as in Major/Minor release steps 3 and 4.
5. `git push` the temp branch.
6. Issue a PR to merge to the release branch.

### Publishing the Release
1. Once the pull request is approved and merged, checkout the release branch and pull the latest changes.
2. Create a new annotated tag with the version number, at the point of the release branch with the fix, e.g., `git tag -as v1.0.1 -m "v1.0.1"`.
3. Push the tag to the remote repository, e.g., `git push origin refs/tags/v1.0.1`.
- Again, better to avoid `git push --tags`.
4. Github Actions will create the release and pull in the fix PR's to the changelog.

## Using a Tagged Release in Another Project
To use the new release in another project, update the project's `Gemfile` to reference the release's tag, e.g., `gem 'event_source', git: 'https://github.com/dchbx/event_source.git', tag: 'v1.0.0'`.

## Git Process diagram
![Git Process Diagram - Gem](docs_assets/release_branching_gem.png)
1 change: 1 addition & 0 deletions docs_assets/NOTE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
This folder is intended for assets used in project internal documentation (RELEASING.md, README.md, etc.).
Binary file added docs_assets/release_branching_gem.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading