npm.io
1.0.0 • Published 2 years ago

@rob.hameetman/semantic-release-config

Licence
MIT
Version
1.0.0
Deps
14
Size
336 kB
Vulns
3
Weekly
0

@rob.hameetman/semantic-release-config

Logo


A package for centralized release management configuration.

React v18.2.0 TypeScript v5.2.2 Rollup v4.1.4
Build Tests w CI/CD


Check It Out Request A Feature Report A Defect


Overview · Getting Started · Development · Testing · Publishing · Contact · License

§1: Overview

This is a semantic-release config used in NPM packages designed for automation and easier prerelease management. Configs create a prerelease version with each PR/branch and allow flexible configuration through environment variables.

PR Prerelease Strategies

Default preid/channel types can be configured by setting the RELEASE_PR_PRERELEASE_STRATEGY environment variable to one of the following values:

RELEASE_PR_PRERELEASE_STRATEGY Example Version Channel
"branch" @rhh/example-package@1.6.8-branch.hotfix-buy-now-button.7 @rhh/example-package@hotfix-buy-now-button
"branch.date" @rhh/example-package@1.6.8-branch.hotfix-buy-now-button.20240613.7 @rhh/example-package@hotfix-buy-now-button
"commit" @rhh/example-package@1.6.8-commit.f73dc97d.1 @rhh/example-package@hotfix-buy-now-button
"commitfull" @rhh/example-package@1.6.8-commit.f73dc97d01d31ca7fad272d80a25b651bab81990.1 @rhh/example-package@hotfix-buy-now-button
"date" @rhh/example-package@1.6.8-date.20240613.4 @rhh/example-package@20240613
"datetime" @rhh/example-package@1.6.8-date.20240613000001.1 @rhh/example-package@20240613
"default" @rhh/example-package@1.6.8-pr.613.7 @rhh/example-package@pr-613
"default.date" @rhh/example-package@1.6.8-pr.613.20240613.7 @rhh/example-package@pr-613
Customizable Preids & Channels

Preids and channels can be easily customized by setting the RELEASE_PR_PRERELEASE_PREID and RELEASE_PR_PRERELEASE_CHANNEL environment variables. Each has access to the following dictionary for customization:

Template Example
${branch} hotfix-buy-now-button
${commit} f73dc97d
${commitfull} f73dc97d01d31ca7fad272d80a25b651bab81990
${date} 20240613
${datetime} 20240613000001
${pr} 613

This table shows examples of each as well as the resulting preid/channel:

RELEASE_PR_PRERELEASE_PREID RELEASE_PR_PRERELEASE_CHANNEL Example Version Channel
"experimental--${commit}" -- 1.6.8-experimental--f73dc97d.1 pr-613
"${branch}.${commit}--${pr}" "x-${pr}--${branch}" 1.6.8-hotfix-buy-now-button.f73dc97d--613.1 x-613--hotfix-buy-now-button
Optional Labels

The preid label can be customized with the RELEASE_PR_PRERELEASE_LABEL environment variable. Setting the value to "omit" will remove the label from the prerelease preid.

RELEASE_PR_PRERELEASE_LABEL RELEASE_PR_PRERELEASE_STRATEGY Example Version
"cr" -- 1.6.8-cr.613.7
"changereq" -- 1.6.8-changereq.613.7
"web" "branch" 1.6.8-web.hotfix-buy-now-button.7
"omit" "commitfull" 1.6.8-f73dc97d01d31ca7fad272d80a25b651bab81990.1

§2: Getting Started

Follow these steps to get the project up and running on your local machine:

1. Prerequisites
  • Node v20+
  • NPM v9+
2. Installation
git clone git@github.com:RobHameetman/semantic-release-config
cd semantic-release-config
npm run setup
3. Editor Configuration

For VSCode, save the following as editor.code-workspace in the project root directory:

{
  "folders": [
    {
      "path": "."
    }
  ],
  "settings": {
    "editor.rulers": [
     80,
     120
    ],
    "eslint.nodeEnv": "development",
    "files.autoSave": "onFocusChange",
    "yaml.format.enable": true,
    "yaml.format.singleQuote": true,
  },
}

back to top

§3: Development

NPM Commands
  • npm run build: Create a production build artifact.
  • npm run format: Perform static analysis and auto-fix errors.
  • npm run reset: Perform a full node_modules/ reset.
  • npm test: Execute the Jest test suite.
Environment Variables
General Options
Variable Description
RELEASE_PLUGIN_PRESET Change the preset used for plugins. Defaults to conventionalcommits.[^1]
RELEASE_PUBLISH_FROM_DIST Set to true if your build pipeline copies package.json into your dist folder.
RELEASE_DEBUG Enable debug mode in semantic-release.
RELEASE_DRY_RUN Perform a dry run of the release.
RELEASE_LOCALLY Run semantic-release outside of your CI/CD pipeline.
Release Rules
Variable Description
RELEASE_SKIP_README_UPDATES Set to true to skip patch increments for README updates if they don't appear in your private registry.
RELEASE_DEPRECATE_AS_MINOR_VERSION If true the deprecate: ... commit type will increment a minor version instead of a patch version.
RELEASE_VERSION_AS_TYPE Allows you to use a specific version as a commit type (e.g. 1.2.1(release): ...).
Custom Commands
Variable Description
RELEASE_EXEC_ANALYZE_COMMITS_CMD A custom shell command to execute during the analyze commits step.
RELEASE_EXEC_GENERATE_NOTES_CMD A custom shell command to execute during the generate notes step.
RELEASE_EXEC_ADD_CHANNEL_CMD A custom shell command to execute during the add channel step.
RELEASE_EXEC_VERIFY_ARTIFACTS_CMD A custom shell command to execute during the verify release step.
RELEASE_EXEC_CWD The path to use as current working directory when executing the shell commands.[^2]
RELEASE_EXEC_FAIL_CMD A custom shell command to execute during the fail step.
RELEASE_EXEC_PREPARE_CMD A custom shell command to execute during the prepare step.
RELEASE_EXEC_PUBLISH_CMD A custom shell command to execute during the publish step.
RELEASE_EXEC_SHELL The shell to use to run the command. If true, runs file inside of a shell.[^3]
RELEASE_EXEC_SUCCESS_CMD A custom shell command to execute during the success step.
RELEASE_EXEC_VERIFY_CONDITIONS_CMD A custom shell command to execute during the verify condition step.
Configuration-specific
Variable Config Description
RELEASE_CANARY_BRANCH Canary The name of your pre-release branch.
RELEASE_CANARY_CHANNEL Canary The name of the channel your pre-releases are tagged by.
RELEASE_BRANCHES Modular Used as the base URL for fetching data from the backend. Add more env variables below.
RELEASE_MAIN_IS_LATEST Modular Used as the base URL for fetching data from the backend. Add more env variables below.

[^1]: Release rules for the angular preset are already included. [^2]: This path is relative to the path from which semantic-release is running. For example if semantic-release runs from /my-project and execCwd is set to buildScripts then the shell command will be executed from /my-project/buildScripts. [^3]: Uses /bin/sh on UNIX and cmd.exe on Windows. A different shell can be specified as a string. The shell should understand the -c switch on UNIX or /d /s /c on Windows.

back to top

§4: Testing

This project uses the following tiers of testing:

  • Unit & Integration Tests: Use npm run test to run all tests.

These commands accept additional inputs following a -- modifier as in the common use-case examples below:

  • npm run test -- --watch: Watch for changes and re-run all tests.
  • npm run test -- src/path/to/test.spec.ts: Run tests in a specific test file.

back to top

§5: Publishing

Creating and merging PRs will create new package versions that you can monitor by vising the Actions tab in Github.

Channels
  • alpha: Used for manual testing in other packages
  • beta: Used for UAT and testing by external consumers
  • next: Everything that will be included in the next major version release
Versioning

This project uses SemVer for versioning. For the versions available, see the tags on this repository.

An beta pre-release version will be published whenever you create a PR and incremented as you update your changes. Once the PR is merged, a release version is created automatically. This is handled with semantic-release.

Major versions should have a corresponding release in Github. Click here to create a new release once your version meets acceptance criteria.

back to top

§6: Contact

For inquiries and additional information, please reach out to:

Rob Hameetman
Front End Architect | Chicago, IL
engineering@robhameetman.com

back to top

§7: License

Distributed under the MIT License.
See the LICENSE file for details.

back to top