@bauglir/semantic-release-configuration v1.1.1
Semantic Release Configuration
A shareable semantic release configuration supporting a range of languages and platforms I tend to work in.
Features
- Analyzes commits using
@semantic-release/commit-analyzer
. - Generates release notes using
@semantic-release/release-notes-generator
. - Updates templated content in a project's root-level
README.md
file with updated version information using@google/semantic-release-replace-plugin
and@semantic-release/git
. - Maintains a
CHANGELOG.md
from the generated release notes using@semantic-release/changelog
and@semantic-release/git
. - (Conditionally) maintains NPM package files, i.e.
package.json
and publishes using@semantic-release/npm
and@semantic-release/git
. - Publishes releases to GitLab using
@semantic-release/gitlab
.
Usage
Create a personal access token, with
api
andwrite_repository
scopes. Make the token available as aGITLAB_TOKEN
orGL_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
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 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 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
<!-- 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
<!-- 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
tooling.