npm package: @m-scott-lassiter/semantic-release-github-npm-config
Description: A common, shareable configuration for publishing on Github and NPM
Author: M. Scott Lassiter
Latest version: 2.0.1

<div align="center">

# @m-scott-lassiter/semantic-release-github-npm-config

[![NPM Version](https://img.shields.io/npm/v/@m-scott-lassiter/semantic-release-github-npm-config)](https://www.npmjs.com/package/@m-scott-lassiter/semantic-release-github-npm-config)
[![NPM Package Size](https://img.shields.io/bundlephobia/min/@m-scott-lassiter/semantic-release-github-npm-config)](https://www.npmjs.com/package/@m-scott-lassiter/semantic-release-github-npm-config)
[![License](https://img.shields.io/github/license/m-scott-lassiter/semantic-release-github-npm-config?color=blue)](https://github.com/M-Scott-Lassiter/semantic-release-github-npm-config/blob/main/LICENSE)

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)

---

[![Build](https://github.com/m-scott-lassiter/semantic-release-github-npm-config/actions/workflows/publish.yml/badge.svg)](https://github.com/m-scott-lassiter/semantic-release-github-npm-config/actions/workflows/publish.yml)
[![Dependency status](https://img.shields.io/librariesio/release/npm/@m-scott-lassiter/semantic-release-github-npm-config)](https://www.npmjs.com/package/@m-scott-lassiter/semantic-release-github-npm-config?activeTab=dependencies)
![Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/npm/@m-scott-lassiter/semantic-release-github-npm-config)
[![Open Issues](https://img.shields.io/github/issues/m-scott-lassiter/semantic-release-github-npm-config)](https://github.com/m-scott-lassiter/semantic-release-github-npm-config/issues)

[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-brightgreen.svg)](#envelope-contact)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](/../../blob/main/CONTRIBUTING.md)

</div>

<!-- Note: The toc tags mark autogenerated content. Do not manually modify the content here -->

<!-- toc -->

-   [Purpose](#purpose)
-   [Install](#install)
-   [Using in Projects](#using-in-projects)
-   [Commits](#commits)
    -   [Commit Header Format](#commit-header-format)
    -   [Commit Body Format](#commit-body-format)
    -   [Commit Footer Format](#commit-footer-format)
-   [Versioning Triggers](#versioning-triggers)
-   [Example Commit Messages](#example-commit-messages)
-   [License and Development](#license-and-development)
-   [Contact](#contact)

<!-- tocstop -->

# Purpose

This is a [shareable configuration](https://semantic-release.gitbook.io/semantic-release/usage/shareable-configurations) for [`semantic-release`](https://semantic-release.gitbook.io/semantic-release/) and documents a standard commit message and continuous release practice.

It uses the following plugins:

-   [`@semantic-release/commit-analyzer`](https://github.com/semantic-release/commit-analyzer)
-   [`@semantic-release/release-notes-generator`](https://github.com/semantic-release/release-notes-generator)
-   [`@semantic-release/changelog`](https://github.com/semantic-release/changelog)
-   [`@semantic-release/npm`](https://github.com/semantic-release/npm)
-   [`@semantic-release/github`](https://github.com/semantic-release/github)
-   [`@semantic-release/git`](https://github.com/semantic-release/git)

# Install

Follow these detailed [installation insructions](/../../blob/main/INSTALLATION.md).

# Using in Projects

_This specification is inspired by and supersedes the [Angular Commit Message](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit). Feel free to copy and modify this section in your own project, or link back here as a common resource._

# Commits

If possible, make [atomic commits](https://en.wikipedia.org/wiki/Atomic_commit), which means:

-   a commit should contain exactly one self-contained functional change
-   a functional change should be contained in exactly one commit
-   a commit should not create an inconsistent state (such as test errors, linting errors, partial fix, feature with documentation etc...)

A complex feature can be broken down into multiple commits as long as each one maintains a consistent state and consists of a self-contained change.

This project uses very precise rules over how Git commit messages must be formatted. This leads to **easier to read commit history**.

Each commit message consists of a **header**, a **body**, and a **footer**.

```bash
<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

The `header` is mandatory and must conform to the [Commit Message Header](#commit-header-format) format.

The `body` is mandatory for all commits except for those of type "docs".
When the body is present it must be at least 20 characters long and must conform to the [Commit Message Body](#commit-body-format) format.

The `footer` is optional unless resolving issues. The [Commit Message Footer](#commit-footer-format) format describes what the footer is used for and the structure it must have.

## Commit Header Format

The header contains succinct description of the change:

-   use the imperative, present tense: "change" not "changed" nor "changes"
-   don't capitalize first letter
-   no dot (.) at the end
-   if the commit is of type `revert`, include `reverts commit <hash>`, where the hash is the SHA of the commit being reverted

```
<type>(<scope>): <short summary>
│ │ │
│ │ └─⫸ Summary in present tense. Not capitalized. No period at the end.
│ │
│ └─⫸ Commit Scope: <custom>|api|contributing|license|readme|security
│
└─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|revert|test
```

**Types**

Required. Must be one of the following:

-   `api`: Non-functional changes to code API documentation that help other developers understand how to use a tool or feature (i.e. intellisense)
-   `build`: Changes that affect the build system configuration, package scripts, or dev dependencies (i.e. adds/remove/modify/update)
-   `ci`: Changes to CI configuration files and scripts (e.g. release configs, YAML scripts)
-   `docs`: Documentation only changes
-   `feat`: Adds or enhances a new matcher
-   `fix`: Fixes a bug in an existing feature. Also used for non-dev dependency updates.
-   `perf`: A code change that improves performance
-   `refactor`: A code change that neither fixes a bug nor adds a feature
-   `revert`: Revert to a commit
-   `test`: Add missing tests or correct existing tests

**Scopes**

Optional. If used, must be one of the following supported scopes:

-   `<custom>`: Used for extending these settings with your own project's requirements
-   `contributing`: Contributions to this guidance or the [Code of Conduct](CODE_OF_CONDUCT.md)
-   `license`: Changes to terms or copyright status within the [license](LICENSE).
    -   _Any change in license type MUST include a BREAKING CHANGE_
-   `readme`: Contributions to the main [README.md](https://github.com/M-Scott-Lassiter/jest-geojson#README)
-   `security`: Changes that address code related security issues or security policies

## Commit Body Format

Provide a plain text description of _why_ you made this change. This is the place for you to explain your thought process, developer to developer. If helpful, include a comparison of the previous behavior with the new behavior to illustrate the change's impact.

If there are breaking changes, start the body with `BREAKING CHANGE: <breaking change summary>.`

## Commit Footer Format

The footer identifies which issues this commit fixes. If none, leave it blank. Otherwise, use the format `Resolves #<issue number>`. If more than one issue is resolved, separate them with a comma.

# Versioning Triggers

This project uses [Semantic Versioning](https://semver.org/) and updates automatically based on specific types used in the commit messages.

Pushes to the main branch causes `semantic-release` to check all commits since the last version for any triggers that would cause a new version. This project extends the defaults:

-   Patch
    -   `fix`
    -   `perf`
    -   `api`
-   Version
    -   `feat`
-   Major
    -   `BREAKING CHANGE`

**Extensions from the [semantic-release default](https://github.com/semantic-release/semantic-release#commit-message-format):**

-   `api` triggers a patch. Only use this type for non-functional changes to code API documentation that help other developers understand how to use the code.
    -   Appropriate use: changing JSDoc comments to make Intellisense more useful for other developers
    -   Inappropriate use: Adding a new function (use `feat`), removing an optional parameter (use `BREAKING CHANGE`)

This keeps API documentation for the end user as a first-class citizen without patching for any and all changes to the README or other supporting docs.

# Example Commit Messages

Minor Version Change:

```
feat(index): add function `foo`

This function adds the key functionality to the project.

Resolves: #1
```

Patch Version Change:

```
fix(index): add function `foo`

This function adds the key functionality to the project.

Resolves: #2
```

Major Version Change:

```
feat(index): add function `foobar`

BREAKING CHANGE: This function does some new useful things. Due to refactoring in the `foo` function, it no longer

Resolves: #3
```

No Change:

```
docs(readme): update readme to document new changes to `foo`
```

```
refactor: change `foo` implementation to faster xyz algorithm
```

Patch Version Change:

```
api: update the JSDoc comments in the `foo` function for parameter clarity
```

# License and Development

This configuration and all other files in this repository are distributed as free and open-source software under the [MIT License](/../../blob/main/LICENSE), © 2022.

Contributions and [bug reports](https://github.com/M-Scott-Lassiter/semantic-release-github-npm-config/issues) welcome.

Leave a :star2: if you find this project useful!

# Contact

Maintained by M. Scott Lassiter.

[![GitHub Badge Profile](https://img.shields.io/badge/GitHub-100000?style=plastic&logo=github&logoColor=white)](https://github.com/M-Scott-Lassiter)
[![Twitter Badge Profile](https://img.shields.io/badge/Twitter-1DA1F2?style=plastic&logo=twitter&logoColor=white)](https://twitter.com/MScottLassiter)
[![LinkedIn Badge Profile](https://img.shields.io/badge/LinkedIn-0077B5?style=plastic&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/mscottlassiter)
[![Stackoverflow Badge Profile](https://img.shields.io/badge/stackoverflow-orange.svg?longCache=true&style=plastic&logo=stackoverflow&logoColor=white)](https://stackoverflow.com/users/6186333/sandpiper)