Skip to content

Commit

Permalink
feat(release-notes-preview): add breaking changes doc check
Browse files Browse the repository at this point in the history 
This adds a new check that enforces that a breaking changes document has been created.
  • Loading branch information
@greenkiwi
greenkiwi committed Sep 15, 2023
1 parent 11fe39f commit 04e002a
Show file tree
Hide file tree
Showing 6 changed files with 375 additions and 55 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/ci.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ jobs:
uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: ./release-notes-preview
- uses: ./lint-release-notes
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
lint:
Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ GitHub Actions for handling releases.

## Actions

### action: [`release-notes-preview`](./release-notes-preview)
### action: [`release-notes-preview`](./lint-release-notes)

Automatically generate release notes using semantic-release and post them as a comment in a pull request with the changes that would be included in the next version of the codebase if the pull request is merged.

See usage [here](./release-notes-preview/README.md#usage).
See usage [here](lint-release-notes/README.md#usage).

Documentation is found [here](./release-notes-preview/README.md).
Documentation is found [here](lint-release-notes/README.md).

## Get Help

Expand Down
57 changes: 57 additions & 0 deletions lint-release-notes/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# GitHub Action Lint Release Notes

## Description

Github action that lints release notes. It generates release notes using semantic-release and posts them as a comment in
a pull request with the changes that would be included in the next version of the codebase if the pull request is
merged. It also will fail if there are breaking changes and no `v<major-version>.md` doc has been created.

## Configuration

### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository.

### Step2: [Add Secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables.

### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes.

## Usage

```yaml
name: Release notes preview

on:
# It's import that this runs on the push event, as semantic release will not run on pull_request events
push:
branches-ignore:
- main

jobs:
lint-release-notes:
name: Lint release notes
steps:
- uses: open-turo/actions-release/lint-release-notes@v2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
```
## Inputs
| parameter | description | required | default |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------- |
| checkout-repo | Perform checkout as first step of action | `false` | true |
| enforce-breaking-changes-docs | Ensure that an appropriate `v<major-version>.md` doc has been created if there are breaking changes in the PR. Fail if required and missing. | `false` | `true` |
| extra-plugins | Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer. Defaults to install @open-turo/semantic-release-config. | `false` | @open-turo/semantic-release-config@^1.4.0 |
| github-token | GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN' | `true` | |
| semantic-version | Specify what version of semantic release to use | `false` | |

## Outputs

N/A

## Runs

This action is an `composite` action.

## Notes

- By default, this action will perform actions/checkout as its first step.
221 changes: 221 additions & 0 deletions lint-release-notes/action.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
name: GitHub Action Release Notes Preview
description: GitHub Action that publishes a new release.
inputs:
checkout-repo:
required: false
description: Perform checkout as first step of action
default: "true"
github-token:
required: true
description: GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN'
default: ${{ github.token }}
enforce-breaking-changes-docs:
required: false
description: Ensure that an appropriate `v<major-version>.md` doc has been created if there are breaking changes in the PR.
default: "true"
extra-plugins:
required: false
description: Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer. Defaults to install @open-turo/semantic-release-config.
default: |
@open-turo/semantic-release-config
semantic-version:
required: false
description: Specify what version of semantic release to use
runs:
using: composite
steps:
- uses: actions/checkout@v3
if: inputs.checkout-repo
with:
fetch-depth: 0
- name: Setup tools
uses: open-turo/action-setup-tools@v1
with:
node: 18.16.1
- uses: jwalton/gh-find-current-pr@v1
id: find-pull-request
with:
state: open
- name: Generate release notes
id: release-notes-preview
uses: open-turo/actions-release/semantic-release@v2
env:
GITHUB_TOKEN: ${{ inputs.github-token }}
with:
branches: ${{ github.ref_name }}
dry-run: true
extra-plugins: ${{ inputs.extra-plugins }}
semantic-version: ${{ inputs.semantic-version }}

# Add release notes preview to PR
- name: Check for release notes comment
uses: peter-evans/find-comment@v2
id: fc-release-notes
if: steps.find-pull-request.outputs.number != ''
with:
issue-number: ${{ steps.find-pull-request.outputs.number }}
comment-author: "github-actions[bot]"
body-includes: "<!-- release notes preview comment -->"
- name: Delete previous release note
if: steps.fc-release-notes.outputs.comment-id != ''
uses: jungwinter/comment@v1
with:
type: delete
comment_id: ${{ steps.fc-release-notes.outputs.comment-id }}
token: ${{ inputs.github-token }}
- name: Comment release notes preview
id: release-notes-preview-comment
uses: peter-evans/create-or-update-comment@v1
if: steps.release-notes-preview.outputs.new-release-notes != '' && steps.find-pull-request.outputs.number != ''
with:
issue-number: ${{ steps.find-pull-request.outputs.number }}
body: |
## Release notes preview
Below is a preview of the release notes if your PR gets merged.
---
<!-- release notes preview comment -->
${{ steps.release-notes-preview.outputs.new-release-notes }}
- name: Create no release created
uses: peter-evans/create-or-update-comment@v1
if: steps.release-notes-preview.outputs.new-release-notes == '' && steps.find-pull-request.outputs.number != ''
with:
issue-number: ${{ steps.find-pull-request.outputs.number }}
body: |
<!-- release notes preview comment -->
## Release notes preview
**_No_ new release will be created.**
If you are expecting a release, you will need to either fix a bug or add a feature.
Chores, CI, docs, refactoring, style and other changes will not trigger a release.
# Ensure that a breaking changes doc has been created
- name: Check for breaking changes comment
uses: peter-evans/find-comment@v2
id: fc-breaking-changes
if: steps.find-pull-request.outputs.number != ''
with:
issue-number: ${{ steps.find-pull-request.outputs.number }}
comment-author: "github-actions[bot]"
body-includes: "<!-- breaking changes comment -->"
- name: Delete previous breaking changes comment
if: steps.fc-breaking-changes.outputs.comment-id != ''
uses: jungwinter/comment@v1
with:
type: delete
comment_id: ${{ steps.fc-breaking-changes.outputs.comment-id }}
token: ${{ inputs.github-token }}
- name: "Check File Existence"
id: breaking-changes-file
if: inputs.enforce-breaking-changes-docs == 'true' && steps.find-pull-request.outputs.number != ''
shell: bash
run: |
echo "Checking for breaking changes file"
set -e
breaking_changes_file_missing=false
breaking_changes_file_default_content=false
breaking_changes_file_exists=false
if [ "${{ steps.release-notes-preview.outputs.new-release-published }}" = "true" ]; then
echo "new release published"
if [ "${{ steps.release-notes-preview.outputs.new-release-type }}" = "major" ]; then
echo "braking change"
file_path="docs/breaking-changes/v${{ steps.release-notes-preview.outputs.new-release-major-version }}.md"
# Check if the file exists
if [ -e "$file_path" ]; then
echo "breaking change doc $file_path exists."
expected_contents="Elaborate and add context to help the developer understand the changes"
breaking_changes_file_exists=true
if grep -Fq "$expected_contents" "$file_path"; then
echo "The file $file_path contains the default contents."
breaking_changes_file_default_content=true
fi
else
echo "breaking change doc $file_path does not exist."
breaking_changes_file_missing=true
fi
fi
fi
echo "Output: "
echo " required=${breaking_changes_file_missing}"
echo " default_content=${breaking_changes_file_default_content}"
echo " exists=${breaking_changes_file_exists}"
echo "required=${breaking_changes_file_missing}" >> $GITHUB_OUTPUT
echo "default_content=${breaking_changes_file_default_content}" >> $GITHUB_OUTPUT
echo "exists=${breaking_changes_file_exists}" >> $GITHUB_OUTPUT
- name: Comment missing breaking changes doc
uses: peter-evans/create-or-update-comment@v1
if: steps.breaking-changes-file.outputs.required == 'true'
with:
issue-number: ${{ steps.find-pull-request.outputs.number }}
body: |
## Error: missing breaking changes documentation
This pull request contains breaking changes, but no documentation has been added to `docs/breaking-changes/v${{ steps.release-notes-preview.outputs.new-release-major-version }}.md`.
<details>
<summary>Instructions for creating breaking changes document:</summary>
```shell
mkdir -p docs/breaking-changes
cat <<EOF > docs/breaking-changes/v${{ steps.release-notes-preview.outputs.new-release-major-version }}.md
# Breaking changes in v${{ steps.release-notes-preview.outputs.new-release-major-version }}
[//]: # "Brief description of current major version release scope. (remove comment after updating)"
## Description of changes
[//]: # "Elaborate and add context to help the developer understand the changes. (remove comment after updating)"
## Upgrade instructions
[//]: # "Required and suggested prerequisites, example code, etc. (remove comment after updating)"
EOF
```
</details>
---
<!-- breaking changes comment -->
- name: Comment missing breaking changes doc
uses: peter-evans/create-or-update-comment@v1
if: steps.breaking-changes-file.outputs.default_content == 'true'
with:
issue-number: ${{ steps.find-pull-request.outputs.number }}
body: |
## Error: breaking changes documentation must be updated
This pull request contains breaking changes, `docs/breaking-changes/v${{ steps.release-notes-preview.outputs.new-release-major-version }}.md` contains the default content.
Please update the content and push changes.
---
<!-- breaking changes comment -->
- name: Get breaking changes doc
uses: mathiasvr/[email protected]
id: breaking-changes-file-contents
if: steps.breaking-changes-file.outputs.exists == 'true'
with:
run: cat docs/breaking-changes/v${{ steps.release-notes-preview.outputs.new-release-major-version }}.md

- name: Append breaking changes doc to release notes preview
uses: peter-evans/create-or-update-comment@v1
if: steps.breaking-changes-file.outputs.exists == 'true'
with:
comment-id: ${{ steps.release-notes-preview-comment.outputs.comment-id }}
body: |
---
## Breaking changes file `docs/breaking-changes/v${{ steps.release-notes-preview.outputs.new-release-major-version }}.md`
${{ steps.breaking-changes-file-contents.outputs.stdout }}
---
- name: Fail if we are checking for the breaking changes doc and it is missing
if: steps.breaking-changes-file.outputs.required == 'true'
shell: bash
run: |
echo "::error::Breaking changes document is missing. Expected: 'docs/breaking-changes/v${{ steps.release-notes-preview.outputs.new-release-major-version }}.md'" && exit 1
- name: Fail if we are checking for the breaking changes doc and it has default content
if: steps.breaking-changes-file.outputs.default_content == 'true'
shell: bash
run: |
echo "::error::Breaking changes document has default content." && exit 1
50 changes: 2 additions & 48 deletions release-notes-preview/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,5 @@
# GitHub Action Release Notes Preview
# DEPRECATED!!!! GitHub Action Release Notes Preview

## Description

Github action that generates release notes using semantic-release and posts them as a comment in a pull request with the changes that would be included in the next version of the codebase if the pull request is merged.

## Configuration

### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository.

### Step2: [Add Secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables.

### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes.

## Usage

```yaml
name: Release notes preview

on:
# It's import that this runs on the push event, as semantic release will not run on pull_request events
push:

jobs:
release-notes:
name: Release notes preview
steps:
- uses: open-turo/actions-release/release-notes-preview@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
```
## Inputs
| parameter | description | required | default |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------- |
| extra-plugins | Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer. Defaults to install @open-turo/semantic-release-config. | `false` | @open-turo/semantic-release-config@^1.4.0 |
| github-token | GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN' | `true` | |
| semantic-version | Specify what version of semantic release to use | `false` | |

## Outputs

N/A

## Runs

This action is an `composite` action.

## Notes

- By default, this action will perform actions/checkout as its first step.
This has been deprecated and will be removed in the future. Please use `open-turo/actions-release/lint-release-notes@v3`.
Loading

0 comments on commit 04e002a

Please sign in to comment.