From 38c2eea219cb4fe7b09dec9b93602aa9a8d44f6a Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Mon, 5 Feb 2024 11:31:12 -0500 Subject: [PATCH 1/8] Included version-changelog-update.yml to automatically bump the app's version and update the CHANGELOG.md; also update relevant docs --- .../workflows/version-changelog-update.yml | 39 ++++++++++++++ CONTRIBUTING.md | 12 +++-- docs/release.md | 54 +++++++++++++++++++ 3 files changed, 100 insertions(+), 5 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..6ab0f0792 --- /dev/null +++ b/.github/workflows/version-changelog-update.yml @@ -0,0 +1,39 @@ +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 }} + 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 config --global user.email "actions@github.com" + git config --global user.name "GitHub Actions" + git push origin HEAD:development diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4fce7ae06..9d532a5ba 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. 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 easily facilitating the release process can be found in [docs/release.md](https://github.com/w3c/aria-at-app/blob/main/docs/release.md) ## License When you submit code changes, your submissions are understood to be under the same [W3C Document License](https://github.com/w3c/aria-at-app/blob/main/LICENSE.md) that covers the project. diff --git a/docs/release.md b/docs/release.md new file mode 100644 index 000000000..90a2c16e2 --- /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 'feature', 'hotfix', 'patch', etc branch + +## Commits + +To easily facilitate CHANGELOG generation, automatic version bumps (using [SEMVER](https://semver.org) - X.Y.Z) and version tagging, commit messages will HAVE to 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 is means is that commits intended to automatically update the [CHANGELOG.md](https://github.com/w3c/aria-at-app/blob/development/CHANGELOG.md) and 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 is that ALL commits have to be written in 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/version-changelog-update/blob/development/.github/workflows/tripps_bump_version.yml) will automatically merge any new changes found in `releases` back into `development`, including the CHANGELOG.md update, along with any last minute changes related to the release. + +## Releasing to production + +When deploying to production, merge `releases` into `main`. From 6311b92f95272fdc522dfa0d0be0df529107ad12 Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Tue, 6 Feb 2024 09:05:55 -0500 Subject: [PATCH 2/8] Update old package.json references --- package.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index 45d01231e..542b00ab2 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" From 9b3d6bf34f100353cba0187dc231f4514e5ac52e Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Tue, 6 Feb 2024 15:24:16 -0500 Subject: [PATCH 3/8] Update NOTE under "Merging to releases" --- docs/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release.md b/docs/release.md index 90a2c16e2..9543597da 100644 --- a/docs/release.md +++ b/docs/release.md @@ -47,7 +47,7 @@ Otherwise, use the squash and merge method, and a type (and scope, if applicable 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/version-changelog-update/blob/development/.github/workflows/tripps_bump_version.yml) will automatically merge any new changes found in `releases` back into `development`, including the CHANGELOG.md update, along with any last minute changes related to the release. +**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 From ed547edc10bd0f5272081e7b69cc1efc5b29c7a5 Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Wed, 7 Feb 2024 09:38:50 -0500 Subject: [PATCH 4/8] Update docs/release.md with suggestion on 'will HAVE to' > 'MUST' Co-authored-by: jugglinmike --- docs/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release.md b/docs/release.md index 9543597da..7314b2f36 100644 --- a/docs/release.md +++ b/docs/release.md @@ -7,7 +7,7 @@ ## Commits -To easily facilitate CHANGELOG generation, automatic version bumps (using [SEMVER](https://semver.org) - X.Y.Z) and version tagging, commit messages will HAVE to 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). +To easily 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 is means is that commits intended to automatically update the [CHANGELOG.md](https://github.com/w3c/aria-at-app/blob/development/CHANGELOG.md) and version must be written in a specific format: ``` From 610dc55141c33bef35bbc9594a54e9b99faca22c Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Wed, 7 Feb 2024 09:41:33 -0500 Subject: [PATCH 5/8] Reduce prescriptive language --- docs/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release.md b/docs/release.md index 7314b2f36..4ffc8bf47 100644 --- a/docs/release.md +++ b/docs/release.md @@ -3,7 +3,7 @@ ## Branching strategy - Checkout the `development` branch after cloning (or forking) the repository -- Create an appropriately named 'feature', 'hotfix', 'patch', etc branch +- Create an appropriately named branch ## Commits From 67b5f42019bb21754e869389f9ef46ccac7de17f Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Thu, 14 Mar 2024 17:41:17 -0500 Subject: [PATCH 6/8] Use github-actions[bot] user for changelog commits --- .github/workflows/version-changelog-update.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/version-changelog-update.yml b/.github/workflows/version-changelog-update.yml index 6ab0f0792..8a269e948 100644 --- a/.github/workflows/version-changelog-update.yml +++ b/.github/workflows/version-changelog-update.yml @@ -26,6 +26,8 @@ jobs: 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 @@ -33,7 +35,4 @@ jobs: git config --global pull.rebase false git pull origin development - name: Update development with version bump from CHANGELOG.md and package.json - run: | - git config --global user.email "actions@github.com" - git config --global user.name "GitHub Actions" - git push origin HEAD:development + run: git push origin HEAD:development From cf8f23f58cbc41b409b63c5d4cea56da3d546c9d Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Thu, 4 Apr 2024 09:38:02 -0500 Subject: [PATCH 7/8] Apply release.md copy tweaks --- docs/release.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/release.md b/docs/release.md index 4ffc8bf47..262698391 100644 --- a/docs/release.md +++ b/docs/release.md @@ -9,7 +9,7 @@ To easily 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 is means is that commits intended to automatically update the [CHANGELOG.md](https://github.com/w3c/aria-at-app/blob/development/CHANGELOG.md) and version must be written in a specific format: +What this is means is commits intended to automatically update the [CHANGELOG.md](https://github.com/w3c/aria-at-app/blob/development/CHANGELOG.md) and version must be written in a specific format: ``` [optional scope]: @@ -26,7 +26,7 @@ Generally, commits in the following format will be sufficient: - `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 is that ALL commits have to be written in this way, explained in [Merging Pull Request](#merging-pull-request). +**NOTE:** This doesn't mean ALL commits have to be written this way, explained in [Merging Pull Request](#merging-pull-request). ## Creating Pull Request From 9a8049dde7eeb58f4c6022ba16b80b1e974bc613 Mon Sep 17 00:00:00 2001 From: Howard Edwards Date: Thu, 4 Apr 2024 16:35:01 -0500 Subject: [PATCH 8/8] Apply suggestions from code review --- CONTRIBUTING.md | 2 +- docs/release.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 889734acd..1d75ff59e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,7 @@ The second maintainer who reviews is responsible for merging the pull request in Maintainers will periodically deploy the `main` and `development` branches to the [live environments](https://github.com/w3c/aria-at-app/wiki). -Additional details on easily facilitating the release process can be found in [docs/release.md](https://github.com/w3c/aria-at-app/blob/main/docs/release.md) +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 index 262698391..87a94073c 100644 --- a/docs/release.md +++ b/docs/release.md @@ -7,9 +7,9 @@ ## Commits -To easily 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). +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 is means is commits intended to automatically update the [CHANGELOG.md](https://github.com/w3c/aria-at-app/blob/development/CHANGELOG.md) and version must be written in a specific format: +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]: