From a66f63095d24128ed84ef8fad9baf42751718cae Mon Sep 17 00:00:00 2001 From: Giamir Buoncristiani Date: Fri, 13 Oct 2023 09:57:41 +0200 Subject: [PATCH] docs(readme): add publishing instructions --- README.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9905897..b0aa4bf 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # axe-apca +[![ci status][gh-action-badge]][gh-action-url] [![npm version][npm-badge]][npm-url] + This package contains custom axe rules and checks for [APCA](https://readtech.org/) Bronze and Silver+ [conformance levels](https://readtech.org/ARC/tests/visual-readability-contrast/?tn=criterion). ## Usage @@ -79,7 +81,21 @@ npm run test:watch ### Publishing -TBC +We use [changesets](https://github.com/changesets/changesets) to automatize the steps necessary to publish to NPM, create GH releases and a changelog. + +- Every time you do work that requires a new release to be published, [add a changesets entry](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md) by running `npx chageset` and follow the instrcutions on screen. (changes that do not require a new release - e.g. changing a test file - don't need a changeset). + - When opening a PR without a corresponding changeset the [changesets-bot](https://github.com/apps/changeset-bot) will remind you to do so. It generally makes sense to have one changeset for PR (if the PR changes do not require a new release to be published the bot message can be safely ignored) +- The [release github workflow](.github/workflows/release.yml) continuosly check if there are new pending changesets in the main branch, if there are it creates a GH PR (`chore(release)` [see example](https://github.com/StackExchange/axe-apca/pull/2)) and continue updating it as more changesets are potentially pushed/merged to the main branch. +- When we are ready to cut a release we need to simply merge the `chore(release)` PR back to main and the release github workflow will take care of publishing the changes to NPM and create a GH release for us. The `chore(release)` PR also give us an opportunity to adjust the automatically generated changelog when necessary (the entry in the changelog file is also what will end up in the GH release notes). + +_The release github workflow only run if the CI workflow (running linter, formatter and tests) is successful: CI is blocking accidental releases_. + +_Despite using changesets to communicate the intent of creating releases in a more explicit way, we still follow [conventional commits standards](https://www.conventionalcommits.org/en/v1.0.0/) for keeping our git history easily parseable by the human eye._ ## License -Copyright 2023 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD). \ No newline at end of file +Copyright 2023 Stack Exchange, Inc and released under the [MIT License](/LICENSE.MD). + +[gh-action-url]: https://github.com/StackExchange/axe-apca/actions/workflows/CI.yml +[gh-action-badge]: https://github.com/StackExchange/axe-apca/actions/workflows/CI.yml/badge.svg?branch=main +[npm-url]: https://npmjs.org/package/axe-apca +[npm-badge]: https://img.shields.io/npm/v/axe-apca.svg \ No newline at end of file