From f981da803a387e008a702ecd36466d4fd8783971 Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Thu, 4 Apr 2024 17:03:53 -0500 Subject: [PATCH] feat: Include workflow for automatic CHANGELOG and version bumps (#913) * Adds `.github/workflows/version-changelog-update.yml` to automatically bump the app's version and updates `CHANGELOG.md` --------- Co-authored-by: jugglinmike --- .../workflows/version-changelog-update.yml | 38 +++++++++++++ CONTRIBUTING.md | 12 +++-- docs/release.md | 54 +++++++++++++++++++ package.json | 8 +-- 4 files changed, 103 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/version-changelog-update.yml create mode 100644 docs/release.md diff --git a/.github/workflows/version-changelog-update.yml b/.github/workflows/version-changelog-update.yml new file mode 100644 index 000000000..8a269e948 --- /dev/null +++ b/.github/workflows/version-changelog-update.yml @@ -0,0 +1,38 @@ +name: Version Bump and Changelog Update + +on: + push: + branches: + - releases + paths-ignore: + - package.json + - CHANGELOG.md + +jobs: + version-changelog-update: + permissions: + contents: write + + runs-on: ubuntu-latest + steps: + - name: Checkout the repository + uses: actions/checkout@v4 + - name: Install NodeJS 18 + uses: actions/setup-node@v4 + with: + node-version: 18 + cache: npm + - name: Conventional Changelog Action + uses: TriPSs/conventional-changelog-action@v3 + with: + github-token: ${{ secrets.github_token }} + git-user-name: github-actions[bot] + git-user-email: github-actions[bot]@users.noreply.github.com + release-count: 0 + preset: conventionalcommits + - name: Pull changes from the development branch + run: | + git config --global pull.rebase false + git pull origin development + - name: Update development with version bump from CHANGELOG.md and package.json + run: git push origin HEAD:development diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df4654cd7..1d75ff59e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,10 +11,10 @@ We use GitHub to host code, track issues and feature requests, and accept pull r ## Issues We use GitHub issues to track bugs, feature requests, and implementation proposals. Report a bug by [opening a new issue](https://github.com/w3c/aria-at-app/issues). -If your issue relates to a specific ARIA-AT test plan or the behavior of the ARIA-AT test renderer, please open an issue in the [aria-at repo](https://github.com/w3c/aria-at/issues). +If your issue relates to a specific ARIA-AT test plan or the behavior of the ARIA-AT test renderer, please open an issue in the [aria-at repository](https://github.com/w3c/aria-at/issues). ## Pull Requests -Pull requests are the best way to propose changes to the codebase. We use [GitHub Flow](https://guides.github.com/introduction/flow/index.html) as a development methodology. +Pull requests are the best way to propose changes to the codebase. We use [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow), and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as development methodologies. If the pull request is not a bug fix, an implementation proposal should first be submitted via a new issue, in order to reach consensus with the maintainers on scope, technical approach, and design implications. @@ -24,7 +24,7 @@ Pull requests should be small and granular, ideally addressing one issue or feat In order to open a pull request: -1. Fork the repo and create your branch from `main`. +1. Fork the repository and create your branch from `development`. 1. If you've added code that should be tested, add tests. See below for some additional guidance on testing. 1. If you've changed APIs, update the documentation. 1. Ensure the test suite passes. @@ -36,9 +36,11 @@ Maintainers with write access to the repository will create branches directly wi ## Reviewing pull requests, merging, and deploying All pull requests, including pull requests opened by maintainers, require code review from two maintainers before merging. -The second maintainer who reviews is responsible for merging the pull request into the protected `main` branch. +The second maintainer who reviews is responsible for merging the pull request into the protected `development` branch. -Maintainers will periodically deploy the `main` branch to the [staging environments](https://github.com/w3c/aria-at-app/wiki). +Maintainers will periodically deploy the `main` and `development` branches to the [live environments](https://github.com/w3c/aria-at-app/wiki). + +Additional details on facilitating the release process can be found in [docs/release.md](https://github.com/w3c/aria-at-app/blob/main/docs/release.md) ## Guidance on Testing diff --git a/docs/release.md b/docs/release.md new file mode 100644 index 000000000..87a94073c --- /dev/null +++ b/docs/release.md @@ -0,0 +1,54 @@ +# Expected workflow for the development to release process + +## Branching strategy + +- Checkout the `development` branch after cloning (or forking) the repository +- Create an appropriately named branch + +## Commits + +To facilitate CHANGELOG generation, automatic version bumps (using [SEMVER](https://semver.org) - X.Y.Z) and version tagging, commit messages MUST follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) practice, which is used in combination with the GitHub Workflow Action, [TriPSs/conventional-changelog-action](https://github.com/TriPSs/conventional-changelog-action). + +What this means is commits intended to automatically update the [CHANGELOG.md](https://github.com/w3c/aria-at-app/blob/development/CHANGELOG.md) and bump the version must be written in a specific format: +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +Additional examples are available [here](https://www.conventionalcommits.org/en/v1.0.0/#examples). + +Generally, commits in the following format will be sufficient: +- `fix: ` will increment **PATCH** in X.Y.**Z** +- `feat: ` will increment **MINOR** in X.**Y**.Z +- `BREAKING CHANGE: OR '!' after any type/scope, eg. feat!: ` will increment **MAJOR** in **X**.Y.Z + - NOTE: `zsh` users will have to surround commit messages with single quotes (`''`) instead of double quotes (`""`), as `!` is a special modifier for `zsh` + +**NOTE:** This doesn't mean ALL commits have to be written this way, explained in [Merging Pull Request](#merging-pull-request). + +## Creating Pull Request + +- Finalize work on branch +- Create Pull Request from work on branch, typically using `development` as the target branch + +## Merging Pull Request + +### Merging to `development` + +Commits to `development` can either be done using a merge commit or it can be squashed. Squashing is preferred, depending on how the commits are structured. + +If the commits in the Pull Request are mainly following the Conventional Commits practice, using a merge commit would be appropriate, so the scoped commits are not lost when being included in the CHANGELOG. + +Otherwise, use the squash and merge method, and a type (and scope, if applicable) MUST be set for the squashed commits' title before merging. + +### Merging to `releases` + +Commits to `releases` MUST be merged with `Create a merge commit`, so that individual PRs or commits which have already been scoped at that point can be properly included in the CHANGELOG.md update. + +**NOTE:** The [version-changelog-update](https://github.com/w3c/aria-at-app/blob/development/.github/workflows/version-changelog-update.yml) workflow will automatically merge any new changes found in `releases` back into `development`, including the CHANGELOG.md update and any last minute changes before the release. + +## Releasing to production + +When deploying to production, merge `releases` into `main`. diff --git a/package.json b/package.json index 9454fbc1c..2f71c7323 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "aria-at-report", + "name": "aria-at-app", "version": "1.0.0", "description": "Run ARIA-AT tests and report results", "main": "server/index.js", @@ -25,14 +25,14 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/bocoup/aria-at-report.git" + "url": "git+https://github.com/w3c/aria-at-app.git" }, "author": "", "license": "SEE LICENSE IN LICENSE.md", "bugs": { - "url": "https://github.com/bocoup/aria-at-report/issues" + "url": "https://github.com/w3c/aria-at-app/issues" }, - "homepage": "https://github.com/bocoup/aria-at-report#readme", + "homepage": "https://github.com/w3c/aria-at-app#readme", "dependencies": { "patch-package": "^6.5.1", "postinstall-postinstall": "^2.1.0"