From b0e60d7c115cf1b04e0da34d4f5d14f85918bccc Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 27 Sep 2022 22:41:55 +1000 Subject: [PATCH] change(release): Automatically split CHANGELOG entries into categories (#5203) * Update release-drafter.yml * Explain where we got the workflow from * Automatically add "trivial" label to dependabot updates * Add categories and auto-labels to release drafter * Update release PR template for automatic release drafter versions * Also strip PR series numbers and leading spaces from changelog entries * Update release note version check * Update label names * Add missing ! in conventional commits regex Co-authored-by: Marek * Make versioning steps more specific Co-authored-by: Marek * Remove conflicting detailed versioning explanations Co-authored-by: Marek Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> --- .../release-checklist.md | 65 ++---- .github/dependabot.yml | 4 +- .github/release-drafter.yml | 192 ++++++++++++++++-- .github/workflows/release-drafter.yml | 20 ++ 4 files changed, 210 insertions(+), 71 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index 61494202..9bbd79b7 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -9,66 +9,25 @@ assignees: '' ## Versioning -### Which Crates to Increment +### How to Increment Versions -To check if any of the top-level crates need version increments: +Zebra follows [semantic versioning](https://semver.org). + +Look for the [draft `zebrad` changelog](https://github.com/ZcashFoundation/zebra/releases) for the automatic version bump. +This version is based on [the labels on the PRs in the release](https://github.com/ZcashFoundation/zebra/blob/main/.github/release-drafter.yml). + +Check that the automatic `zebrad` version increment is correct: +1. If we're releasing a mainnet network upgrade, increment the `major` version of all Zebra crates +2. If we're not releasing a mainnet network upgrade, check for features, major changes, deprecations, and removals. If this release has any, it is a `minor` release + +If we're not doing a `major` release, you need to check which crates have changed: 1. Go to the zebra GitHub code page: https://github.com/ZcashFoundation/zebra -2. Check if the last commit was a Zebra version bump, or something else - -
- -Alternatively you can: -- Use the github compare tool and check the `main` branch against the last tag ([Example](https://github.com/ZcashFoundation/zebra/compare/v1.0.0-alpha.15...main)) -- Use `git diff --stat origin/main` - -
+2. Check if the last commit to each crate is a Zebra version bump. If it is a version bump, the crate has not changed since the last release. Once you know which crates have changed: - [ ] Increment the crates that have new commits since the last version update - [ ] Increment any crates that depend on crates that have changed - [ ] Keep a list of the crates that haven't been incremented, to include in the PR - -### How to Increment Versions - -Zebra follows [semantic versioning](https://semver.org). - -Semantic versions look like: MAJOR`.`MINOR`.`PATCH[`-`TAG`.`PRE-RELEASE] - -
- -#### Pre-Release Crates - -Pre-Release versions have a `TAG` like "alpha" or "beta". For example: `1.0.0-alpha.0` - -1. Increment the `PRE-RELEASE` version for the crate. - -#### Unstable Crates - -Unstable versions have a `MAJOR` version of zero. For example: `0.1.0` - -1. Follow stable crate versioning, but increment the `MINOR` version for breaking changes - -#### Stable Crates - -For example: `1.0.0` - -Increment the first version component in this list, and reset the other components to zero: -1. MAJOR versions for breaking public API changes and removals - * check for types from dependencies that appear in the public API -2. MINOR versions for new features -3. PATCH versions for bug fixes - * includes dependency updates that don't impact the public API - -### Reviewing Version Bumps - -Check for missed changes by going to: -`https://github.com/ZcashFoundation/zebra/tree//` -Where `` is the hash of the last commit in the version bump PR. - -If any Zebra or Tower crates have commit messages that are **not** a version bump, we have missed an update. -Also check for crates that depend on crates that have changed. They should get a version bump as well. - -
### Version Locations diff --git a/.github/dependabot.yml b/.github/dependabot.yml index dfc26fa4..2e92b5a5 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -7,8 +7,9 @@ updates: timezone: America/New_York open-pull-requests-limit: 10 labels: - - 'A-dependencies' + - 'C-trivial' - 'A-rust' + - 'A-dependencies' - 'P-Low :snowflake:' - package-ecosystem: github-actions directory: '/' @@ -17,6 +18,7 @@ updates: timezone: America/New_York open-pull-requests-limit: 10 labels: + - 'C-trivial' - 'A-infrastructure' - 'A-dependencies' - 'P-Low :snowflake:' diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 4e6f6f06..828e8c10 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -1,19 +1,177 @@ -prerelease: true -categories: - - title: 'Features' - labels: - - 'feature' - - 'enhancement' - - title: 'Bug Fixes' - labels: - - 'fix' - - 'bugfix' - - 'bug' - - title: 'Maintenance' - label: 'chore' -change-template: '- $TITLE (#$NUMBER)' -change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks. -template: | - ## Changes +# Configuration for automatic Zebra CHANGELOGs and PR tagging +# +# Based on: +# https://github.com/marketplace/actions/release-drafter#example +# Automatically label PRs based on their branch, title, or changed files. +# This helps categorise PRs in the CHANGELOG. +autolabeler: + - label: 'C-security' + branch: + - '/secur/i' + title: + - '/secur/i' + - label: 'C-removed' + branch: + - '/remov/i' + title: + - '/remov/i' + - label: 'C-deprecated' + branch: + - '/deprecat/i' + title: + - '/deprecat/i' + - label: 'C-feature' + branch: + - '/add/i' + - '/feat/i' + title: + - '/add/i' + - '/feat/i' + - label: 'C-enhancement' + branch: + - '/chang/i' + title: + - '/chang/i' + - label: 'C-bug' + branch: + - '/fix/i' + - '/bug/i' + title: + - '/fix/i' + - '/bug/i' + # Changes that are almost always trivial for users + - label: 'C-trivial' + branch: + - '/clean/i' + - '/chore/i' + - '/clippy/i' + title: + - '/clean/i' + - '/chore/i' + - '/clippy/i' + files: + # Regular changes that don't need to go in the CHANGELOG + - 'CHANGELOG.md' + - 'zebra-consensus/src/checkpoint/*-checkpoints.txt' + # Developer-only changes + - 'zebra-utils' + - '.gitignore' + # Test-only changes + - 'zebra-test' + - '.cargo/config.toml' + - 'clippy.toml' + # CI-only changes + - '.github' + - '.codespellrc' + - 'codecov.yml' + - 'deny.toml' + +# The release name, tag, and settings for the draft CHANGELOG. +name-template: 'Zebra $RESOLVED_VERSION' +tag-template: 'v$RESOLVED_VERSION' +tag-prefix: 'v' +prerelease: true + +# Categories in rough order of importance to users. +# Based on https://keepachangelog.com/en/1.0.0/ +category-template: '### $TITLE' +categories: + - title: 'Security' + labels: + - 'C-security' + # Other labels that are usually security issues + - 'I-bad-code' + - 'I-bad-data' + - 'I-consensus' + - 'I-crash' + - 'I-destructive' + - 'I-hang' + - 'I-lose-funds' + - 'I-privacy' + - 'I-remote-node-overload' + - 'I-unbounded-growth' + - 'I-unsound' + - title: 'Removed' + labels: + - 'C-removal' + - 'C-breaking' + - title: 'Deprecated' + labels: + - 'C-deprecation' + # TODO: when release drafter has per-category templates, add this to the Deprecated category template: + # 'These features might be removed in Zebra $NEXT_MINOR_VERSION' + - title: 'Added' + labels: + - 'C-feature' + - title: 'Changed' + labels: + - 'C-enhancement' + - title: 'Fixed' + labels: + - 'C-bug' + # Other labels that are usually bugs + - 'I-build-fail' + - 'I-integration-fail' + - 'I-panic' + # TODO: if we're happy with the trivial PRs, use "exclude-labels:" instead + - title: 'Trivial *TODO:* put this in a PR comment, not the CHANGELOG' + labels: + - 'C-trivial' + - 'C-cleanup' + +# The next release's $RESOLVED_VERSION, based on the labels of the PRs in the release. +# +# In Zebra, we use major versions for mainnet network upgrades, +# and minor versions for less significant breaking changes. +version-resolver: + major: + labels: + # We increment the major release version manually + minor: + labels: + - 'C-feature' + - 'C-breaking' + - 'C-removal' + - 'C-deprecation' + # We increment the patch version for every release + default: patch + +# How PR names get turned into CHANGELOG entries. +change-template: '- $TITLE ([#$NUMBER]($URL))' +sort-by: title +sort-direction: ascending +# Characters escaped when converting PR titles to CHANGELOG entries. +# Add ` to disable code blocks. +change-title-escapes: '\<*_&#@' +# Strip PR series numbers, leading spaces, and conventional commit prefixes from PR titles. +replacers: + - search: '/- [0-9\. ]*([a-zA-Z0-9\(\)!]+:)?/' + replace: '- ' + +# The list of contributors to each release. +exclude-contributors: + - 'dependabot' # 'dependabot[bot]' + - 'mergifyio' # 'mergify[bot]' + +# The template for the draft CHANGELOG. +template: | + ## [Zebra $RESOLVED_VERSION](https://github.com/ZcashFoundation/zebra/releases/tag/v$RESOLVED_VERSION) - *TODO*: date + + This release *TODO*: a summary of the significant user-visible changes in the release + + ### Breaking Changes + + This release has the following breaking changes: + - *TODO*: Check the `Removed` section for any breaking changes + - *TODO*: Add a short description of the user impact of each breaking change, and any actions users need to take + $CHANGES + + ### Contributors + + Thank you to everyone who contributed to this release, we couldn't make Zebra without you: + $CONTRIBUTORS + + +# the trailing newlines in the template are deliberate diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml index 23969a55..d3987e0a 100644 --- a/.github/workflows/release-drafter.yml +++ b/.github/workflows/release-drafter.yml @@ -1,5 +1,8 @@ # Creates a draft release with all the PR names since the last release. # https://github.com/ZcashFoundation/zebra/releases +# +# Workflow is based on: +# https://github.com/marketplace/actions/release-drafter#usage name: Release Drafter on: @@ -7,16 +10,33 @@ on: push: branches: - main + # pull_request event is required only for autolabeler + pull_request: + # Only following types are handled by the action, but one can default to all as well + #types: [opened, reopened, synchronize] + # pull_request_target event is required for autolabeler to support PRs from forks + pull_request_target: + #types: [opened, reopened, synchronize] # Manually update the draft release without waiting for a PR to merge workflow_dispatch: +permissions: + contents: read + jobs: update_release_draft: + permissions: + # write permission is required to create a github release + contents: write + # write permission is required for autolabeler + # otherwise, read permission is required at least + pull-requests: write runs-on: ubuntu-latest steps: # Drafts your next Release notes - uses: release-drafter/release-drafter@v5 with: config-name: release-drafter.yml + #disable-autolabeler: true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}