A conventional-changelog-core fork with bug fixes
[![Black Lives Matter!][x-badge-blm-image]][x-badge-blm-link]
[![Last commit timestamp][x-badge-lastcommit-image]][x-badge-repo-link]
[![Codecov][x-badge-codecov-image]][x-badge-codecov-link]
[![Source license][x-badge-license-image]][x-badge-license-link]
[![Uses Semantic Release!][x-badge-semanticrelease-image]][x-badge-semanticrelease-link]
[![NPM version][x-badge-npm-image]][x-badge-npm-link]
[![Monthly Downloads][x-badge-downloads-image]][x-badge-downloads-link]
# xchangelog (@-xun/changelog)
This [conventional-changelog-core][1] fork slightly tweaks the original to fix
some bugs and bundle type definitions that are more well-formed.
Among the bugs fixed by this fork is one where [conventional-changelog-core][1],
when given a release commit with multiple tags, will only accept the first tag
in the list as the version tag if it matches (i.e. starts with
[`tagPrefix`][4]). Without this fix, when the _actual_ matching version tag is
not first in the list, strange things happen.
Multiple tags on the same release commit is useful when, for instance, you
transmute a polyrepo into a monorepo and need to alias the original
`v${version}`-style tags with the more monorepo-friendly
`${package-name}@${version}`-style tags.
> [!NOTE]
>
> The only reason to use xchangelog over [conventional-changelog-core][1] is if
> you are using an [symbiote][2]-powered project or you need the bug fixes.
> Otherwise, just use [conventional-changelog][1].
---
- [Install](#install)
- [Usage](#usage)
- [Appendix](#appendix)
- [Published Package Details](#published-package-details)
- [License](#license)
- [Contributing and Support](#contributing-and-support)
- [Contributors](#contributors)
## Install
To install xchangelog:
```shell
npm install --save-dev @-xun/changelog
```
If you want to use a specific version of xchangelog, provide its semver:
```shell
npm install @-xun/changelog
```
> [!NOTE]
>
> xchangelog installations can reuse the "conventional-changelog-core" name so
> that plugins with conventional-changelog-core as a peer dependency are able to
> recognize xchangelog's presence. For example:
>
> ```bash
> npm install --save-dev conventional-changelog-core@npm:@-xun/changelog
> ```
## Usage
```js
import conventionalChangelogCore from '@-xun/changelog';
conventionalChangelogCore().pipe(process.stdout); // or any writable stream
```
## Appendix
See the [`conventionalChangelogCore`][3] upstream documentation for more
details.
### Published Package Details
This is an [ESM-only package][x-pkg-esm-wine] for use in Node.js versions that
are not end-of-life. For TypeScript users, this package supports both `"Node10"`
and `"Node16"` module resolution strategies.
Expand details
That means ESM source will load this package via `import { ... } from ...` or
`await import(...)` and CJS source will load this package via dynamic
`import()`. This has several benefits, the foremost being: less code
shipped/smaller package size, avoiding [dual package
hazard][x-pkg-dual-package-hazard] entirely, distributables are not
packed/bundled/uglified, and a drastically less complex build process.
The glaring downside, which may or may not be relevant, is that CJS consumers
cannot `require()` this package and can only use `import()` in an asynchronous
context. This means, in effect, CJS consumers may not be able to use this
package at all.
Each entry point (i.e. `ENTRY`) in [`package.json`'s
`exports[ENTRY]`][x-repo-package-json] object includes one or more [export
conditions][x-pkg-exports-conditions]. These entries may or may not include: an
[`exports[ENTRY].types`][x-pkg-exports-types-key] condition pointing to a type
declaration file for TypeScript and IDEs, a
[`exports[ENTRY].module`][x-pkg-exports-module-key] condition pointing to
(usually ESM) source for Webpack/Rollup, a `exports[ENTRY].node` and/or
`exports[ENTRY].default` condition pointing to (usually CJS2) source for Node.js
`require`/`import` and for browsers and other environments, and [other
conditions][x-pkg-exports-conditions] not enumerated here. Check the
[package.json][x-repo-package-json] file to see which export conditions are
supported.
Note that, regardless of the [`{ "type": "..." }`][x-pkg-type] specified in
[`package.json`][x-repo-package-json], any JavaScript files written in ESM
syntax (including distributables) will always have the `.mjs` extension. Note
also that [`package.json`][x-repo-package-json] may include the
[`sideEffects`][x-pkg-side-effects-key] key, which is almost always `false` for
optimal [tree shaking][x-pkg-tree-shaking] where appropriate.
Add your contributions