fix: refactor documentation for semantic-release (#80)

BrightspaceUI · Aug 10, 2023 · d9e816f · d9e816f
1 parent 0d4f3d6
commit d9e816f
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 91 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
 ```