|
| 1 | +# @simple-release/core |
| 2 | + |
| 3 | +[![ESM-only package][package]][package-url] |
| 4 | +[![NPM version][npm]][npm-url] |
| 5 | +[![Node version][node]][node-url] |
| 6 | +[![Dependencies status][deps]][deps-url] |
| 7 | +[![Install size][size]][size-url] |
| 8 | +[![Build status][build]][build-url] |
| 9 | +[![Coverage status][coverage]][coverage-url] |
| 10 | + |
| 11 | +[package]: https://img.shields.io/badge/package-ESM--only-ffe536.svg |
| 12 | +[package-url]: https://nodejs.org/api/esm.html |
| 13 | + |
| 14 | +[npm]: https://img.shields.io/npm/v/@simple-release/core.svg |
| 15 | +[npm-url]: https://www.npmjs.com/package/@simple-release/core |
| 16 | + |
| 17 | +[node]: https://img.shields.io/node/v/@simple-release/core.svg |
| 18 | +[node-url]: https://nodejs.org |
| 19 | + |
| 20 | +[deps]: https://img.shields.io/librariesio/release/npm/@simple-release/core |
| 21 | +[deps-url]: https://libraries.io/npm/@simple-release%2Fcore/tree |
| 22 | + |
| 23 | +[size]: https://packagephobia.com/badge?p=@simple-release/core |
| 24 | +[size-url]: https://packagephobia.com/result?p=@simple-release/core |
| 25 | + |
| 26 | +[build]: https://img.shields.io/github/actions/workflow/status/TrigenSoftware/simple-release-tools/tests.yml?branch=main |
| 27 | +[build-url]: https://github.com/TrigenSoftware/simple-release-tools/actions |
| 28 | + |
| 29 | +[coverage]: https://coveralls.io/repos/github/TrigenSoftware/simple-release-tools/badge.svg?branch=main |
| 30 | +[coverage-url]: https://coveralls.io/github/TrigenSoftware/simple-release-tools?branch=main |
| 31 | + |
| 32 | +A simple tool to release projects with monorepo support. |
| 33 | + |
| 34 | +<hr /> |
| 35 | +<a href="#install">Install</a> |
| 36 | +<span> • </span> |
| 37 | +<a href="#usage">Usage</a> |
| 38 | +<span> • </span> |
| 39 | +<a href="#why">Why</a> |
| 40 | +<span> • </span> |
| 41 | +<a href="#addons">Addons</a> |
| 42 | +<span> • </span> |
| 43 | +<a href="#custom-addons">Custom addons</a> |
| 44 | +<br /> |
| 45 | +<hr /> |
| 46 | + |
| 47 | +## Install |
| 48 | + |
| 49 | +```bash |
| 50 | +# pnpm |
| 51 | +pnpm add @simple-release/core |
| 52 | +# yarn |
| 53 | +yarn add @simple-release/core |
| 54 | +# npm |
| 55 | +npm i @simple-release/core |
| 56 | +``` |
| 57 | + |
| 58 | +## Usage |
| 59 | + |
| 60 | +```js |
| 61 | +import { Releaser } from '@simple-release/core' |
| 62 | +import { PnpmProject } from '@simple-release/pnpm' |
| 63 | +import { GithubReleaseCreator } from '@simple-release/github-release' |
| 64 | + |
| 65 | +const project = new PnpmProject() |
| 66 | + |
| 67 | +await new Releaser(project) |
| 68 | + .bump() |
| 69 | + .commit() |
| 70 | + .tag() |
| 71 | + .push() |
| 72 | + .release(new GithubReleaseCreator({ |
| 73 | + token: process.env.GITHUB_TOKEN |
| 74 | + })) |
| 75 | + .publish() |
| 76 | + .run() |
| 77 | +``` |
| 78 | + |
| 79 | +Monorepo example: |
| 80 | + |
| 81 | +```js |
| 82 | +import { Releaser } from '@simple-release/core' |
| 83 | +import { PnpmWorkspacesProject } from '@simple-release/pnpm' |
| 84 | +import { GithubReleaseCreator } from '@simple-release/github-release' |
| 85 | + |
| 86 | +const project = new PnpmWorkspacesProject({ |
| 87 | + mode: 'independent' |
| 88 | +}) |
| 89 | + |
| 90 | +await new Releaser(project) |
| 91 | + .bump() |
| 92 | + .commit() |
| 93 | + .tag() |
| 94 | + .push() |
| 95 | + .release(new GithubReleaseCreator({ |
| 96 | + token: process.env.GITHUB_TOKEN |
| 97 | + })) |
| 98 | + .publish() |
| 99 | + .run() |
| 100 | +``` |
| 101 | + |
| 102 | +## Why |
| 103 | + |
| 104 | +There no good tool to release projects with conventional-changelog support and with good monorepo support. |
| 105 | + |
| 106 | +## Addons |
| 107 | + |
| 108 | +- [npm](https://github.com/TrigenSoftware/simple-release-tools/tree/main/packages/npm) |
| 109 | +- [pnpm](https://github.com/TrigenSoftware/simple-release-tools/tree/main/packages/pnpm) |
| 110 | +- [github-release](https://github.com/TrigenSoftware/simple-release-tools/tree/main/packages/github-release) |
| 111 | + |
| 112 | +## Custom addons |
| 113 | + |
| 114 | +### Manifest |
| 115 | + |
| 116 | +If you want to create your own project addon, firstly you can need to create a custom manifest adapter. Manifest adapter is a class that reads basic information about the project from the manifest file (like `package.json`) and can write version to it. |
| 117 | + |
| 118 | +```js |
| 119 | +import { ProjectManifest } from '@simple-release/core' |
| 120 | + |
| 121 | +export class CustomManifest extends ProjectManifest { |
| 122 | + static Filename = 'custom.json' |
| 123 | + |
| 124 | + async readManifest() { |
| 125 | + // Read the manifest file and return its parsed content |
| 126 | + } |
| 127 | + |
| 128 | + async getName() { |
| 129 | + // Return the name of the project |
| 130 | + } |
| 131 | + |
| 132 | + async getVersion() { |
| 133 | + // Return the current version of the project |
| 134 | + } |
| 135 | + |
| 136 | + async isPrivate() { |
| 137 | + // Return true if the project is private |
| 138 | + } |
| 139 | + |
| 140 | + async writeVersion(version, dryRun) { |
| 141 | + // Write the new version to the manifest file |
| 142 | + // If dryRun is true, do not write the file, just change the version in memory |
| 143 | + } |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +For more detailed example you can look at the [PackageJsonManifest](./src/manifest/packageJson.ts) implementation. |
| 148 | + |
| 149 | +### Project |
| 150 | + |
| 151 | +Project is a class that represents the project and provides methods to work with it: |
| 152 | + |
| 153 | +- bump version |
| 154 | +- get information from git |
| 155 | +- publish the project |
| 156 | +- etc. |
| 157 | + |
| 158 | +Most of the methods are implemented in base class [GenericProject](./src/project/project.ts) and you can extend it to create your own project class. |
| 159 | + |
| 160 | +In most casses you need just prepare options for the base class and implement `publish` method (like it is done in [PackageJsonProject](./src/project/packageJson.ts)). |
| 161 | + |
| 162 | +```js |
| 163 | +import { GenericProject } from '@simple-release/core' |
| 164 | + |
| 165 | +export class CustomProject extends GenericProject { |
| 166 | + constructor(options) { |
| 167 | + super({ |
| 168 | + ...options, |
| 169 | + manifest: new CustomManifest(options.path) |
| 170 | + }) |
| 171 | + } |
| 172 | + |
| 173 | + async publish(options) { |
| 174 | + // Publish the project |
| 175 | + } |
| 176 | +} |
| 177 | +``` |
| 178 | + |
| 179 | +There also is a base class for monorepo projects - [GenericMonorepoProject](./src/project/monorepo.ts). It provides methods to work with monorepo projects and you can extend it to create your own monorepo project class (alos see [PackageJsonMonorepoProject](./src/project/packageJsonMonorepo.ts)). |
| 180 | + |
| 181 | +### Release creator |
| 182 | + |
| 183 | +Release creator is a class that creates a release in the remote repository (like GitHub, GitLab, etc.) or wherever you want. It is used in the `release` step of the releaser. |
| 184 | + |
| 185 | +Signature of the class is very simple, you just need to implement `create` method: |
| 186 | + |
| 187 | +```js |
| 188 | +import { GenericReleaseCreator } from '@simple-release/core' |
| 189 | + |
| 190 | +export class CustomReleaseCreator extends GenericReleaseCreator { |
| 191 | + async create({ project, dryRun, logger }) { |
| 192 | + // Create the release in the remote repository |
| 193 | + // You can use `project` to get information about the project |
| 194 | + // or more precisely you can use `project.getgetReleaseData()` to get the data for the release |
| 195 | + } |
| 196 | +} |
| 197 | +``` |
0 commit comments