From d9e816f0fee1dee6240610d5d785a709359ffc61 Mon Sep 17 00:00:00 2001 From: Dave Lockhart Date: Thu, 10 Aug 2023 11:51:36 -0400 Subject: [PATCH] fix: refactor documentation for semantic-release (#80) --- README.md | 39 ++----------------- .../templates/configured/_README.md | 15 +------ .../release/templates/configured/_README.md | 39 ++----------------- .../test-unit/templates/configured/_README.md | 18 ++++++--- 4 files changed, 20 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 3922830..51a83d0 100644 --- a/README.md +++ b/README.md @@ -52,41 +52,8 @@ TODO: Pull requests welcome! -## Versioning & Releasing +### Versioning and Releasing -> TL;DR: Commits prefixed with `fix:` and `feat:` will trigger patch and minor releases when merged to `main`. Read on for more details... +This repo is configured to use `semantic-release`. Commits prefixed with `fix:` and `feat:` will trigger patch and minor releases when merged to `main`. -The [semantic-release GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) is called from the `release.yml` GitHub Action workflow to handle version changes and releasing. - -### Version Changes - -All version changes should obey [semantic versioning](https://semver.org/) rules: -1. **MAJOR** version when you make incompatible API changes, -2. **MINOR** version when you add functionality in a backwards compatible manner, and -3. **PATCH** version when you make backwards compatible bug fixes. - -The next version number will be determined from the commit messages since the previous release. Our semantic-release configuration uses the [Angular convention](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) when analyzing commits: -* Commits which are prefixed with `fix:` or `perf:` will trigger a `patch` release. Example: `fix: validate input before using` -* Commits which are prefixed with `feat:` will trigger a `minor` release. Example: `feat: add toggle() method` -* To trigger a MAJOR release, include `BREAKING CHANGE:` with a space or two newlines in the footer of the commit message -* Other suggested prefixes which will **NOT** trigger a release: `build:`, `ci:`, `docs:`, `style:`, `refactor:` and `test:`. Example: `docs: adding README for new component` - -To revert a change, add the `revert:` prefix to the original commit message. This will cause the reverted change to be omitted from the release notes. Example: `revert: fix: validate input before using`. - -### Releases - -When a release is triggered, it will: -* Update the version in `package.json` -* Tag the commit -* Create a GitHub release (including release notes) -* Deploy a new package to NPM - -### Releasing from Maintenance Branches - -Occasionally you'll want to backport a feature or bug fix to an older release. `semantic-release` refers to these as [maintenance branches](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#maintenance-branches). - -Maintenance branch names should be of the form: `+([0-9])?(.{+([0-9]),x}).x`. - -Regular expressions are complicated, but this essentially means branch names should look like: -* `1.15.x` for patch releases on top of the `1.15` release (after version `1.16` exists) -* `2.x` for feature releases on top of the `2` release (after version `3` exists) +To learn how to create major releases and release from maintenance branches, refer to the [semantic-release GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) documentation. diff --git a/src/generators/default-content/templates/configured/_README.md b/src/generators/default-content/templates/configured/_README.md index 92ef439..73c84a9 100644 --- a/src/generators/default-content/templates/configured/_README.md +++ b/src/generators/default-content/templates/configured/_README.md @@ -33,19 +33,6 @@ To make your usage of `<%= tagName %>` accessible, use the following properties |--|--| | | | -## Developing, Testing and Contributing +## Developing and Contributing After cloning the repo, run `npm install` to install dependencies. - -### Linting - -```shell -# eslint and stylelint -npm run lint - -# eslint only -npm run lint:eslint - -# stylelint only -npm run lint:style -``` diff --git a/src/generators/release/templates/configured/_README.md b/src/generators/release/templates/configured/_README.md index 78fab11..2ceb03b 100644 --- a/src/generators/release/templates/configured/_README.md +++ b/src/generators/release/templates/configured/_README.md @@ -1,39 +1,6 @@ -## Versioning & Releasing +### Versioning and Releasing -> TL;DR: Commits prefixed with `fix:` and `feat:` will trigger patch and minor releases when merged to `main`. Read on for more details... +This repo is configured to use `semantic-release`. Commits prefixed with `fix:` and `feat:` will trigger patch and minor releases when merged to `main`. -The [semantic-release GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) is called from the `release.yml` GitHub Action workflow to handle version changes and releasing. - -### Version Changes - -All version changes should obey [semantic versioning](https://semver.org/) rules: -1. **MAJOR** version when you make incompatible API changes, -2. **MINOR** version when you add functionality in a backwards compatible manner, and -3. **PATCH** version when you make backwards compatible bug fixes. - -The next version number will be determined from the commit messages since the previous release. Our semantic-release configuration uses the [Angular convention](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) when analyzing commits: -* Commits which are prefixed with `fix:` or `perf:` will trigger a `patch` release. Example: `fix: validate input before using` -* Commits which are prefixed with `feat:` will trigger a `minor` release. Example: `feat: add toggle() method` -* To trigger a MAJOR release, include `BREAKING CHANGE:` with a space or two newlines in the footer of the commit message -* Other suggested prefixes which will **NOT** trigger a release: `build:`, `ci:`, `docs:`, `style:`, `refactor:` and `test:`. Example: `docs: adding README for new component` - -To revert a change, add the `revert:` prefix to the original commit message. This will cause the reverted change to be omitted from the release notes. Example: `revert: fix: validate input before using`. - -### Releases - -When a release is triggered, it will: -* Update the version in `package.json` -* Tag the commit -* Create a GitHub release (including release notes) -* Deploy a new package to NPM - -### Releasing from Maintenance Branches - -Occasionally you'll want to backport a feature or bug fix to an older release. `semantic-release` refers to these as [maintenance branches](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#maintenance-branches). - -Maintenance branch names should be of the form: `+([0-9])?(.{+([0-9]),x}).x`. - -Regular expressions are complicated, but this essentially means branch names should look like: -* `1.15.x` for patch releases on top of the `1.15` release (after version `1.16` exists) -* `2.x` for feature releases on top of the `2` release (after version `3` exists) +To learn how to create major releases and release from maintenance branches, refer to the [semantic-release GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) documentation. diff --git a/src/generators/test-unit/templates/configured/_README.md b/src/generators/test-unit/templates/configured/_README.md index 519616a..e3a661f 100644 --- a/src/generators/test-unit/templates/configured/_README.md +++ b/src/generators/test-unit/templates/configured/_README.md @@ -1,13 +1,21 @@ ### Testing +To run the full suite of tests: + ```shell -# lint & run headless unit tests npm test +``` -# unit tests only -npm run test:headless +Alternatively, tests can be selectively run: -# debug or run a subset of local unit tests -npm run test:headless:watch +```shell +# eslint +npm run lint:eslint + +# stylelint +npm run lint:style + +# unit tests +npm run test:headless ```