npm package: @bauglir/semantic-release-configuration
Description: A shareable semantic release configuration supporting a range of languages and platforms I tend to work in.
Author: Joris Kraak
Latest version: 1.1.1

# Semantic Release Configuration

A shareable [semantic release](https://semantic-release.gitbook.io)
configuration supporting a range of languages and platforms I tend to work in.

## Features

- Analyzes commits using
  [`@semantic-release/commit-analyzer`][semantic-release-commit-analyzer-plugin-url].
- Generates release notes using
  [`@semantic-release/release-notes-generator`][semantic-release-notes-generator-plugin-url].
- Updates templated content in a project's root-level `README.md` file
  with updated version information using
  [`@google/semantic-release-replace-plugin`][semantic-release-replace-plugin-url]
  and [`@semantic-release/git`][semantic-release-git-plugin-url].
- Maintains a `CHANGELOG.md` from the generated release notes using
  [`@semantic-release/changelog`][semantic-release-changelog-plugin-url] and
  [`@semantic-release/git`][semantic-release-git-plugin-url].
- (Conditionally) maintains NPM package files, i.e. `package.json` and
  publishes using [`@semantic-release/npm`][semantic-release-npm-plugin-url]
  and [`@semantic-release/git`][semantic-release-git-plugin-url].
- Publishes releases to GitLab using
  [`@semantic-release/gitlab`][semantic-release-gitlab-plugin-url].

## Usage

- Create a [personal access token][gitlab-pat-url], with `api` and
  `write_repository` scopes. Make the token available as a `GITLAB_TOKEN` or
  `GL_TOKEN` CI/CD variable of the project using the configuration.

  For improved security, _use a unique token for every project this
  configuration is used in_!

- Use this shareable semantic release configuration by including it in the
  [`extends`][semantic-release-extends-configuration-url] configuration for the
  project to be semantically released.

### JavaScript Packages

JavaScript packages are detected based on the presence of a `package.json` file
in the root of the project.

- Create an [NPM token][npm-token-url] to be able to publish to an NPM
  registry. Make the token available as an `NPM_TOKEN` CI/CD variable of the
  project using the configuration.

  See [the plugin's configuration
  instructions][semantic-release-npm-plugin-configuration-url] for details and
  alternatives.

### Templated Content in `README.md` Files

The configuration will look for `__NEXT_SEMANTIC_RELEASE_VERSION__` tokens in
templates in a project's root-level `README.md` and replace them with the
version that is being released. This is, for instance, useful for automatically
keeping installation instructions up-to-date.

Templated content is created using HTML comments and has the following
structure:

- A `<!-- START_VERSIONED_TEMPLATE` token,
- the template itself with one or more
  `__NEXT_SEMANTIC_RELEASE_VERSION__` tokens,
- a comment closing tag `-->`,
- (optionally) content that was previously templated,
- a comment closing the templated content `<!-- END_VERSIONED_TEMPLATE -->`.

More concretely a section in a `README` that looks like

```markdown
<!-- START_VERSIONED_TEMPLATE

The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!

-->
<!-- END_VERSIONED_TEMPLATE -->
```

would, after a v1.2.3 release using the configuration has been triggered,
become

```markdown
<!-- START_VERSIONED_TEMPLATE

The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!

-->

The next semantically released version will be v1.2.3!

<!-- END_VERSIONED_TEMPLATE -->
```

Note that the `v` is in the template! The version as derived by the semantic
release tooling does not contain that prefix.

## Troubleshooting

### Publishing the initial release of a scoped JavaScript package

Creating the initial release of a scoped JavaScript may fail if the package is
intended to be public and the person creating the release not having paid for
private packages. This results in an error similar to

```
npm ERR! 402 Payment Required - PUT https://registry.npmjs.org/@<scope>%2f<package-name> -
You must sign up for private packages
```

When this happens, publish the initial release manually using `npm publish --access=public`
after making sure the local copy of the project to be released is up-to-date.

When this happens, it is typically also necessary to create the initial GitHub
release by hand from the tag and changelog that was created by the
[`semantic-release`][semantic-release-url] tooling.

[gitlab-pat-url]: https://gitlab.com/-/profile/personal_access_tokens
[npm-token-url]: https://www.npmjs.com/settings/bauglir/tokens/
[semantic-release-changelog-plugin-url]: https://github.com/semantic-release/changelog
[semantic-release-commit-analyzer-plugin-url]: https://github.com/semantic-release/commit-analyzer
[semantic-release-extends-configuration-url]: https://semantic-release.gitbook.io/semantic-release/usage/configuration#extends
[semantic-release-git-plugin-url]: https://github.com/semantic-release/git
[semantic-release-gitlab-plugin-url]: https://github.com/semantic-release/gitlab
[semantic-release-notes-generator-plugin-url]: https://github.com/semantic-release/release-notes-generator
[semantic-release-npm-plugin-configuration-url]: https://github.com/semantic-release/npm#npm-registry-authentication
[semantic-release-npm-plugin-url]: https://www.npmjs.com/package/@semantic-release/npm
[semantic-release-replace-plugin-url]: https://github.com/google/semantic-release-replace-plugin
[semantic-release-url]: https://semantic-release.gitbook.io/