semantic-release-changelog-update

Dependencies

Update changelog using semantic-release without triggering release. Use as a plugin or a standalone command.

🏠 Homepage | 🗃 Repository | 📦 NPM | 📚 Documentation | 🐛 Issue Tracker

🪑 Table of Content

🧰 Features
👶 Install
🚀 Usage
🤖 API
🔮 Details
⏳ Changelog
🛠 Developing
🏗 Roadmap
🤝 Contributing
🧙 Contributors
⭐ Show your support
🐙 Community
🔗 Related Projects
👨‍🔧 Maintainers
📝 License

🧰 Features

Update changelog using semantic-release without triggering release.

Useful for updating changelog on pull request CI builds. Such updated changelog is commited to the branch that triggered the build, so the changelog can be reviewed before the branch is merged.

The plugin updates changelog only when latest changelog version is below or at package.json's version, so it's safe to use in CI builds.

Use either as a plugin or call it as a standalone function.

Works with pull-request-triggered CI builds. Branches are detected from env-ci's prBranch and branch.

To work with push-triggered CI builds, specify the headBranch to be env-ci's branch.

To use outside CI environment, specify both headBranch and baseBranch options.

👶 Install

Requirements

git cli with the permission to push and commit to remote

Installation

npm install semantic-release-changelog-update

🚀 Usage

See how the plugin is used within this project.

Note: This plugin works with git cli and temporarily creates a branch on remote named temp/semantic-release/<branch-name>.

The plugin changes the branch that semantic-release is working with. Therefore it is not recommended to use it with other plugins that might depend on commits, or that intend to release something, as these would be working with the temporary branch.

As a function

import changelogUpdate from 'semantic-release-changelog-update';
 
// Returns promise. Once the promise is resolved the `headBranch` will have
// a new commit with the updated changelog created and pushed to remote.
changelogUpdate({
  options: {
    // To update the changelog without a release, semantic-release is started
    // on non-release branch. Hence we need to allow it to start on non-release
    // branches, and instead specify the release branches in
    // `pluginOptions.releaseBranches`
    branches: [
      // branch that headBranch is based off. You can think of it as
      // the branch that headBranch should merge to
      baseBranch,
      // branch that will have the changelog updated
      headBranch,
      // other unrelated branches
      otherBranch,
    ],
  },
  pluginOptions: {
    headBranch, // defaults to envCi.prBranch
    baseBranch, // defaults to envCi.branch
    changelogFile, // defaults to `./CHANGELOG.md`
    releaseBranches: [baseBranch],
  },
});

The function accepts an object with 3 properties:

options - options object passed as 1st argument to semantic-release
environment - env object passed as 2nd argument to semantic-release
pluginOptions - options object specific to the plugin, same as defining plugins options via config.plugins.

As a plugin

To use the package as a plugin, you must run semantic-release with dryRun and noCi flags (dryRun flag can be disabled if explicitly configured).

Add the plugin to semantic-release config.

{
  "dryRun": true,
  "ci": false,
  ...
  "plugins": [
    "semantic-release-changelog-update/plugin"
  ]
}

If you are using release.config.js, you can specify the plugin path also by using the plugin attribute.

const changelogUpdate = require('semantic-release-changelog-update');
module.exports = {
  dryRun: true,
  ci: false,
  ....
  plugins: [
    changelogUpdate.plugin,
  ]
}

You can pass options like this:

{
  ....
  "plugins": [
    [
      "semantic-release-changelog-update/plugin",
      {
        "message": "custom commit message",
        "prepareChangelog": "./path/to/func"
      }
    ]
  ]
}

Then call semantic-release, e.g. with cli.

npx semantic-release --no-ci --dry-run

🤖 API

TypeDoc API documentation can be found here.

Options

Option	Description	Type	Default
`baseBranch`	Name of the git branch that will be used as a base for rebase. This is a branch that should contain all commits that are reported in the changelog.	string	env-ci's `prBranch`
`headBranch`	Name of the git branch whose commits will be rebased onto beadBranch. This is a branch that should the commits with new changes.	string	env-ci's `branch`
`releaseBranches`	The plugin is intended to be triggered only when the branch we are applying the changes to (base branch) is one of the release branches as defined in semantic-release `branches` option. This is different from semantic-release, which checks if the current / head branch is one of the release branches. `releaseBranches` thus defines when the plugin should be triggered. Generally, this value should be the same as the `branches` option used in semantic-release config. It accepts the same format as semantic-release `branches` option.	(string \| BranchOption)[]	`['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
`pattern`	Regular expression (RegExp or string) to use to find and capture the latest release version from changelog. Captured version must must be either first capture group or group tagged as `version`.	string \| Regexp	Matches `1.2.3` in `## [1.2.3](https://...`
`prepareChangelog`	Function that modifies the changelog file content before the file is parsed for version and changes are inserted. Signature: `(content: string, config: object, context: object) => string`	function	-
`requireDryRun`	Whether an error should be raised if the plugin is used without the semantic-release's `dryRun` flag. Note that changing this option is highly discouraged as this plugin is not indended to be used in release enviroment. If you need to update changelog during release, use [@semantic-release/changelog] plugin instead.	boolean	`true`

The plugin additionally accepts options that are passed to other plugin it uses:

Plugin	Notes
@semantic-release/commit-analyzer	All options are passed forward.
@semantic-release/release-notes-generator	All options are passed forward.
@semantic-release/git	The `assets` option is ignored and overriden by `changelogFile`.
@semantic-release/changelog	All options are passed forward.

🔮 Details

In the background, this plugin does the following:

Creates a temporary branch named temp/semantic-release/<branch-name>. This branch is based on baseBranch with commits rebased from headBranch on top of it, so we have a branch that contains all (current + new) commits without polluting any working branches.
The temporary branch is pushed to remote so commit-analyzer can find it and extract commits.
If commit-analyzer found no release-worthy commits, the temporary branch is removed and the semantic-release end the pipeline.
After commit-analyzer, the plugin calls release-notes-generator, changelog and git passing the temporary branch as the branch these plugins should work against. This updates the changelog and pushes it to the temporary branch.
Lastly, the commit containing the changelog update is pushed to the headBranch and the temporary branch is removed.

⏳ Changelog

This projects follows semantic versioning. The changelog can be found here.

🛠 Developing

If you want to contribute to the project or forked it, this guide will get you up and going.

🏗 Roadmap

No roadmap currently planned for this package. However, if you have ideas how it could be improved, please be sure to share it with us by opening an issue.

🤝 Contributing

Contributions, issues and feature requests are welcome! Thank you ❤️

Feel free to dive in! See current issues, open an issue, or submit PRs.

How to report bugs, feature requests, and how to contribute and what conventions we use is all described in the contributing guide.

When contributing we follow the Contributor Covenant. See our Code of Conduct.

🧙 Contributors

Contributions of any kind welcome. Thanks goes to these wonderful people ❤️

Recent and Top Contributors

_{Generated using Hall of Fame.}

All Contributors

Contribution type emoji legend

No additional contributors. Be the first one!

_{This project follows the all-contributors specification.}

⭐ Show your support

Give a ⭐️if this project helped you!

🐙 Community

🔗 Related Projects

This project is a plugin for semantic-release.

👨‍🔧 Maintainers

👤 Juro Oravec

Twitter: @JuroOravec
GitHub: @JuroOravec
LinkedIn: @jurooravec
Sourcerer: @JuroOravec

📝 License

This project is MIT licensed.