\n\n \n\n# xrelease (@-xun/release)\n\n\n\nThis [semantic-release][1] fork slightly tweaks the original so that it can work\nwith both polyrepos and monorepos (see [below][31]).\n\n> [!NOTE]\n>\n> The only reason to use xrelease over [semantic-release][1] is if you are using\n> an [symbiote][2]-powered project, your repository uses annotated tags, you\n> need the bug fixes, or your repository is a monorepo. Otherwise, just use\n> [semantic-release][1].\n\n\n\n---\n\n\n\n\n\n\n- [Install](#install)\n- [Additional Features](#additional-features)\n - [Lightweight and Annotated Tag Support](#lightweight-and-annotated-tag-support)\n - [Support for Monorepos](#support-for-monorepos)\n- [Example](#example)\n- [Appendix](#appendix)\n - [Published Package Details](#published-package-details)\n - [License](#license)\n- [Contributing and Support](#contributing-and-support)\n - [Contributors](#contributors)\n\n\n\n\n\n \n\n## Install\n\n\n\nTo install xrelease:\n\n```shell\nnpm install --save-dev semantic-release@npm:@-xun/release\n```\n\nIf you want to use a specific version of xrelease, provide its semver:\n\n```shell\nnpm install --save-dev semantic-release@npm:@-xun/release@1.2.3\n```\n\n> [!NOTE]\n>\n> xrelease installations reuse the \"semantic-release\" name so that plugins with\n> semantic-release as a peer dependency are able to recognize xrelease's\n> presence.\n\n## Additional Features\n\nxrelease offers a couple improvements over upstream:\n\n### Lightweight and Annotated Tag Support\n\nBoth [lightweight and annotated tags][3] are supported.\n\n> `man git-tag` says:\n>\n> Annotated tags are meant for release while lightweight tags are meant for\n> private or temporary object labels.\n\n### Support for Monorepos\n\nMonorepo support is implemented via the existing [`tagFormat`][4] configuration\noption and the introduction of two new options: [`branchRangePrefix`][5] and\n[`gitLogOptions`][6].\n\n> [!WARNING]\n>\n> These options have only been tested in [release configuration files][7] and\n> might not be available via CLI.\n\nOnce properly configured, xrelease should be run once per package to be\nreleased, with the current working directory set to the root of each respective\npackage.\n\nFor monorepos, if the current working directory does not contain the\nrepository's release configuration file, use `--extends` to refer to its\nlocation explicitly (e.g. `--extends ../../release.config.js`); xrelease\nsupports using `--extends` to load plugins from `/node_modules/` directories\nhigher up in the repository tree. Further, a tool like [Turbo][8] can be used to\norchestrate package releases in dependency order.\n\n> [!NOTE]\n>\n> See [babel-plugin-tester's `release.config.js`][9] (polyrepo), [symbiote's\n> `release.config.js`][2] (hybridrepo) or [unified-utils's\n> `release.config.js`][10] (monorepo) for complete functional examples of\n> xrelease configurations in the wild.\n>\n> See the [symbiote wiki][11] or the [git diff between this repo and\n> upstream][12] for technical details.\n\nThe extended configuration options are:\n\n#### `tagFormat`\n\nType: `string`\\\nDefault: `\"v${version}\"`\n\nThe [git tag][13] format used by xrelease to create and identify releases. When\ncutting a new release, its corresponding tag name will be [generated][14] using\n`tagFormat`.\n\n`tagFormat` is key to proper monorepo support since it dictates which existing\ntags belong to the current package to be released and which belong to other\npackages that should be filtered out.\n\nTo support a simple monorepo that uses \"@\"-syntax for its release tags (e.g.\n`my-package@1.2.3`), your [release configuration][7] might include:\n\n```javascript\n// Tell xrelease what package-specific tags look like\ntagFormat: `${cwdPackageName}@\\${version}`;\n```\n\n> [!CAUTION]\n>\n> `\\${version}` (or `${version}` in a non-template string literal) is a [Lodash\n> template variable][14] while `${cwdPackageName}` is a variable in a [template\n> string literal][15]. That is: you are responsible for defining\n> `cwdPackageName`, while `\\${version}` is replaced by xrelease. Additionally,\n> each `tagFormat` value must contain the `version` variable exactly once, and\n> the whole `tagFormat` value must compile to a valid git reference or\n> commit-ish.\n\nTo refactor a polyrepo (that uses the standard semantic-release \"v\"-syntax for\nits tags) into a monorepo (that uses the \"@\"-syntax for its tags), optionally\nwith a root package, use [`@-xun/scripts`'s \"renovate\" command][16]:\n`npx symbiote project renovate --regenerate-assets --preset ...`.\n\n#### `gitLogOptions`\n\nType: `{ paths?: string | string[], flags?: string | string[] }`\\\nDefault: `\"v${version}\"`\n\nThe [git log][17] [command line arguments][18] used by xrelease to select\ncommits for [further analysis][19]. Currently, `gitLogOptions` has two valid\noptions: `flags` and `paths`, which correspond to\n[`git log -- `][20].\n\n`gitLogOptions` is key to proper monorepo support since it dictates what commits\nbelong to the current package to be released and which belong to other packages\nthat should be filtered out.\n\nTo support a monorepo attempting to release a new version of `my-package-1`,\nyour [release configuration][7] might include:\n\n```javascript\ngitLogOptions: {\n // Tell xrelease to consider only commits that modify files under these paths\n paths: [\n ':(exclude)../my-package-2',\n ':(exclude)../my-package-3',\n ':(exclude)../my-package-4'\n ];\n}\n```\n\nIn this example, we used [exclusion pathspecs][21] to create a denylist of paths\nwe _didn't want_ instead of an allowlist of paths we do want. Either approach is\nviable depending on project structure; however, using exclusions ensures\nimportant changes that happen outside the package's root directory (such as\nchanges to a shared unpublished library) are considered by xrelease when\n[analyzing commits][19].\n\nNote how the given pathspecs are relative to e.g.\n`/home/user/my-project/packages/my-package-1`. That's because xrelease should\nalways be run at the root of the package to be released.\n\nThe pathspec syntax we're using happens to work for releasing each of the other\npackages as well, assuming they are all share the same parent directory, e.g.\n`/home/user/my-project/packages`. If we wanted to release `my-package-2` next,\nwe would replace `':(exclude)../my-package-2'` with\n`':(exclude)../my-package-1'` and run xrelease again.\n\nTo support a polyrepo instead, your [release configuration][7] might include:\n\n```javascript\ngitLogOptions: {\n // Tell xrelease not to filter commits at all and instead consider everything\n paths: [];\n}\n```\n\nOr we could omit the `gitLogOptions` object from `release.config.js` entirely,\nwhich would be equivalent.\n\nFinally, you can use `flags` to ensure [`git log`][20] is invoked with certain\nflags. For instance, we can tell xrelease to ignore all commits reachable by an\n\"initial\" commit (including said commit itself). This could be useful if we\nforked a large project with many thousands of commits (conventional or\notherwise) that should be ignored by the commit analyzer:\n\n```javascript\ngitLogOptions: {\n // Tell xrelease to filter commits created after the latest commit (including\n // itself) with \"[INIT]\" suffixing its subject, a reference we acquired by\n // running: `git log -1 --pretty=format:%H --fixed-strings --grep '\\\\[INIT]$'`\n flags: ref ? [`^${ref}`] : [];\n}\n```\n\nYou can pass any flag that [`git log`][20] understands.\n\n#### `branchRangePrefix`\n\nType: `string`\\\nDefault: `\"\"`\n\nThe value that prefixes the [names][22] of relevant [maintenance branches][23].\nThis is used internally by xrelease to generate the proper [`branches`][24]\nconfigurations for maintenance branches that refer to particular packages in a\nmonorepo, and can be left undefined in a polyrepo.\n\n> [!CAUTION]\n>\n> The `branchRangePrefix` string must **only match maintenance branches**! If\n> you also define a non-maintenance branch with a name starting with\n> `branchRangePrefix`, xrelease's behavior is undefined.\n\nTo support a simple monorepo that uses \"[package-name@x.y.z][25]\"-syntax for its\nmaintenance branch names (e.g. `my-package@1.2.3`), your [release\nconfiguration][7] might include:\n\n```javascript\n// Tell xrelease to remove this string from maintenance branch names when\n// resolving their respective ranges and channels\nbranchRangePrefix: `${cwdPackageName}@`,\nbranches: [\n // Tell xrelease what package-specific maintenance branch names look like.\n // Specifically: they must begin with `branchRangePrefix`\n `${cwdPackageName}@+([0-9])?(.{+([0-9]),x}).x`,\n 'main'\n]\n```\n\nTo refactor a polyrepo (that uses the standard semantic-release \"x.y.z\"-syntax\nfor its maintenance branch names) into a monorepo (that uses the\n\"[package@x.y.z][26]\"-syntax for its maintenance branch names), optionally with\na root package, use [`@-xun/scripts`'s \"renovate\" command][16]:\n`npx symbiote project renovate --regenerate-assets --preset ...`.\n\n## Example\n\nPutting the new configuration options together, we could use what follows to\nrelease packages from the `/home/user/my-project` hybridrepo (a monorepo with a\nroot package), which was formerly a polyrepo that we turned into a monorepo by\ngiving its root `package.json` file a [`workspaces`][27] key and [creating\nscoped aliases of existing maintenance branches and tags][16].\n\nThe `my-project` repo contains the four packages `my-package-1` through\n`my-package-4` under `/home/user/my-project/packages/*` along with a\n`/home/user/my-project/package.json` file containing the name of the root\npackage (`my-root-package`) and a `/home/user/my-project/src` directory\ncontaining the root package's source code.\n\nWe can push changes to `main`, which is our primary release branch that\npublishes to one or more packages' respective [`@latest` release channel][28]\n(the default for NPM projects). Or we can push changes to `canary`, which will\npublish to one or more packages' respective [`@canary` release channel][29]. We\ncan also push changes to a `package-name@x.y.z` branch, where `package-name`\nrepresents the name of the monorepo package and `x.y.z` represents the\n[maintenance branch `range`][30].\n\n```javascript\n// ./release.config.js\n\nfunction makeConfiguration() {\n const { cwdPackage } = getCurrentWorkingDirectoryPackageInformation();\n const isCwdPackageTheRootPackage = isRootPackage(cwdPackage);\n const gitLogPathspecs = getExcludedDirectoryPathspecs(cwdPackage);\n const cwdPackageName = cwdPackage.json.name;\n\n return {\n // Tell xrelease what package-specific tags look like\n tagFormat: `${cwdPackageName}@\\${version}`,\n // Tell xrelease to remove this string from maintenance branch names when\n // resolving their respective ranges and channels\n branchRangePrefix: `${cwdPackageName}@`,\n gitLogOptions: {\n // Tell xrelease to exclude commits from the other packages\n paths: gitLogPathspecs\n },\n branches: [\n // Tell xrelease what package-specific maintenance branch names look like.\n // Specifically: they must begin with `branchRangePrefix`\n `${cwdPackageName}@+([0-9])?(.{+([0-9]),x}).x`,\n // If this is the root package, we could accept old-style branch names for\n // the sake of compatibility. But it's usually better to just create new\n // branch names aliases matching the `${cwdPackageName}@` pattern\n //...(isCwdPackageTheRootPackage ? ['+([0-9])?(.{+([0-9]),x}).x'] : []),\n 'main',\n {\n name: 'canary',\n channel: 'canary',\n prerelease: true\n }\n ],\n plugins: [\n // ...\n ]\n };\n}\n\nmodule.exports = makeConfiguration();\n```\n\n\n\n## Appendix\n\n\n\n\n### Published Package Details\n\nThis is an [ESM-only package][x-pkg-esm-wine] built by Babel for use in Node.js\nversions that are not end-of-life. For TypeScript users, this package supports\nboth `\"Node10\"` and `\"Node16\"` module resolution strategies.\n\n\n\n\nExpand details\n\nThat means ESM source will load this package via `import { ... } from ...` or\n`await import(...)` and CJS source will load this package via dynamic\n`import()`. This has several benefits, the foremost being: less code\nshipped/smaller package size, avoiding [dual package\nhazard][x-pkg-dual-package-hazard] entirely, distributables are not\npacked/bundled/uglified, and a drastically less complex build process.\n\nThe glaring downside, which may or may not be relevant, is that CJS consumers\ncannot `require()` this package and can only use `import()` in an asynchronous\ncontext. This means, in effect, CJS consumers may not be able to use this\npackage at all.\n\nEach entry point (i.e. `ENTRY`) in [`package.json`'s\n`exports[ENTRY]`][x-repo-package-json] object includes one or more [export\nconditions][x-pkg-exports-conditions]. These entries may or may not include: an\n[`exports[ENTRY].types`][x-pkg-exports-types-key] condition pointing to a type\ndeclaration file for TypeScript and IDEs, a\n[`exports[ENTRY].module`][x-pkg-exports-module-key] condition pointing to\n(usually ESM) source for Webpack/Rollup, a `exports[ENTRY].node` and/or\n`exports[ENTRY].default` condition pointing to (usually CJS2) source for Node.js\n`require`/`import` and for browsers and other environments, and [other\nconditions][x-pkg-exports-conditions] not enumerated here. Check the\n[package.json][x-repo-package-json] file to see which export conditions are\nsupported.\n\nNote that, regardless of the [`{ \"type\": \"...\" }`][x-pkg-type] specified in\n[`package.json`][x-repo-package-json], any JavaScript files written in ESM\nsyntax (including distributables) will always have the `.mjs` extension. Note\nalso that [`package.json`][x-repo-package-json] may include the\n[`sideEffects`][x-pkg-side-effects-key] key, which is almost always `false` for\noptimal [tree shaking][x-pkg-tree-shaking] where appropriate.\n\n\n\n\n\n\n### License\n\n\n\nSee [LICENSE][x-repo-license].\n\n\n\n## Contributing and Support\n\nConsider contributing to upstream\n[semantic-release][x-badge-semanticrelease-image] instead.\n\n\n\n\n### Contributors\n\n\n\n\n\n\n[](#contributors-)\n\n\n\n\nThanks goes to these wonderful people ([emoji\nkey][x-repo-all-contributors-emojis]):\n\n\n\n\n\n\n
![](\"https://raw.githubusercontent.com/Xunnamius/xrelease/refs/heads/main/logo.png\"){kind=logo}
\n![\"Bernard\"/](\"https://avatars.githubusercontent.com/u/656017?v=4?s=100\")
![](\"https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg\"){kind=logo}
\n Add your contributions\n \n