Skip to content

Commit

Permalink
Merge pull request #46 from ghiscoding/chore/lerna-cli
Browse files Browse the repository at this point in the history
BREAKING CHANGE: use `lerna` CLI for all commands, fixes #28
  • Loading branch information
ghiscoding committed Mar 15, 2022
2 parents 3603ee8 + 35f2800 commit 49d2fa1
Show file tree
Hide file tree
Showing 87 changed files with 2,378 additions and 1,119 deletions.
2 changes: 1 addition & 1 deletion .github/FUNDING.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: # Replace with a single Open Collective username
ko_fi: N4N679OT
ko_fi: ghiscoding
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
custom: # Replace with a single custom sponsorship URL
130 changes: 67 additions & 63 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
# Lerna-Lite 🐉
### Previously known as "ws-conventional-version-roller"

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
Expand All @@ -12,19 +11,28 @@
[![codecov](https://codecov.io/gh/ghiscoding/lerna-lite/branch/main/graph/badge.svg)](https://codecov.io/gh/ghiscoding/lerna-lite)
[![Actions Status](https://github.com/ghiscoding/lerna-lite/workflows/CI%20Build/badge.svg)](https://github.com/ghiscoding/lerna-lite/actions)

### License
[MIT License](LICENSE)
## Lerna-Lite is a super light version of the original [Lerna](https://github.com/lerna/lerna)

## Lerna-Lite
A super light fork of Lerna, only 3 commands were extracted from the original [Lerna](https://github.com/lerna/lerna) (as shown below).
- [About Lerna-Lite](https://github.com/ghiscoding/lerna-lite#about-lerna-lite)
- [Why create this lib/fork?](https://github.com/ghiscoding/lerna-lite#why-create-this-libfork)
- [See it in Action](https://github.com/ghiscoding/lerna-lite/wiki/Release-Demo)
- [README Badge](https://github.com/ghiscoding/lerna-lite#readme-badge)
- [Installation](https://github.com/ghiscoding/lerna-lite#installation)
- [`lerna.json` config file](https://github.com/ghiscoding/lerna-lite/wiki/Lerna.json)
- [Migration for Lerna users](https://github.com/ghiscoding/lerna-lite#migration-for-lerna-users)
- [Troubleshooting](https://github.com/ghiscoding/lerna-lite/wiki/Troubleshooting)
- Commands
- [`publish`](https://github.com/ghiscoding/lerna-lite/tree/main/packages/publish#readme) - publish each workspace package (included with CLI)
- [`version`](https://github.com/ghiscoding/lerna-lite/tree/main/packages/version#readme) - create new version for each workspace package (included with CLI)
- [`run`](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run#readme) - run npm script in each workspace package (separate install)

**Note:** Since the [Run](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run) command is totally optional, we created separate CLIs to handle each commands, see below.
---

| Command | CLI | Description | Included |
|---------|-------------|-------------| ---------|
| [version](https://github.com/ghiscoding/lerna-lite/tree/main/packages/version) | [ws-roller](https://github.com/ghiscoding/lerna-lite/tree/main/packages/cli#installation) 📰 | create new version for each workspace package | Yes |
| [publish](https://github.com/ghiscoding/lerna-lite/tree/main/packages/publish) | [ws-roller](https://github.com/ghiscoding/lerna-lite/tree/main/packages/cli#installation) 📰 | publish each workspace package | Yes |
| [run](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run) | [ws-runner](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run#installation) 🏃 | run npm script in each workspace package | Optional |
## License
[MIT License](LICENSE)

## About Lerna-Lite
Lerna-Lite differs from the original [Lerna](https://github.com/lerna/lerna) in the sense that it only includes 3 commands (1 is optional) out of 15 commands that the original Lerna has. It also assume that you have already setup a workspace through NPM, Yarn Workspaces or any other technology that will take care of the symlinks and with that in mind Lerna-Lite does not include the `bootstrap` command, so make sure your workspace is properly setup before installing Lerna-Lite.

## Why create this lib/fork?
Mainly for the following reasons:
Expand All @@ -33,15 +41,16 @@ Mainly for the following reasons:
3. add some little extras

### This lib will help you with
##### [Version](https://github.com/ghiscoding/lerna-lite/tree/main/packages/version) & [Publish](https://github.com/ghiscoding/lerna-lite/tree/main/packages/publish) commands (`ws-roller`)
- Automate the rolling of new Versions (independent or fixed) for all your packages
##### [Version](https://github.com/ghiscoding/lerna-lite/tree/main/packages/version) & [Publish](https://github.com/ghiscoding/lerna-lite/tree/main/packages/publish) commands
- Automate the rolling of new Versions (independent or fixed) for all your workspace packages
- it will automatically add Commit & Tag your new Version in Git & create new Release in GitHub when enabled
- Automate the creation of Changelogs for all your packages by reading all [Conventional Commits](https://www.conventionalcommits.org/)
- each package will get its own changelog and a combined changelog will also be created in the root
- Automate the repository Publish of your new versions for all your packages
- it could push to NPM or any other repository platform
##### [Run](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run) command (`ws-runner`)
- Automate the repository Publish of your new versions for all your packages (NPM or other platform)

##### [Run](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run) command (optional)
- [Run](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run) is an optional package that will help you run npm script in parallel and in topological order.

## Lerna-Lite Packages

| Package Name | Version | Description | Changes |
Expand All @@ -58,7 +67,12 @@ You want to see a demo project? Sure, you're looking at it 😉
Yes indeed, this lib was created as an NPM Workspace specifically for the purpose of demoing and testing of its own code. All changelogs and published versions were created by the lib itself, how sweet is that? You will also find that it has its own [lerna.json](https://github.com/ghiscoding/lerna-lite/blob/main/lerna.json) config file just as well as you would when using the lib.

### See it in Action 🎦
You can see a small video of a new version release on this [Release Demo - Wiki](https://github.com/ghiscoding/lerna-lite/wiki/Release-Demo) - Confused with all the options? You can watch this great YouTube video [How to Use Lerna](https://www.youtube.com/watch?v=p6qoJ4apCjA), the Lerna-Lite Options are all the same as Lerna + extras.
You can see a small video of a new version release on this [Release Demo - Wiki](https://github.com/ghiscoding/lerna-lite/wiki/Release-Demo) - Confused with all the options? Consult the multiple links below.

#### References
- [Release Demo - Wiki](https://github.com/ghiscoding/lerna-lite/wiki/Release-Demo) - Lerna-Lite demo (animated gif)
- [How to Use Lerna](https://www.youtube.com/watch?v=p6qoJ4apCjA) - YouTube video
- [Lerna Release Workflow](https://github.com/curiousNoob/lerna-release-workflow) - GitHub Template

### README Badge
Using Lerna-Lite? Add a README badge to show it off: [![lerna--lite](https://img.shields.io/badge/maintained%20with-lerna--lite-d428ff)](https://github.com/ghiscoding/lerna-lite)
Expand All @@ -68,77 +82,67 @@ Using Lerna-Lite? Add a README badge to show it off: [![lerna--lite](https://img
```

## Installation
| Command | Install | Description | Included |
|---------|-------------|-------------| ---------|
| 📰 [version](https://github.com/ghiscoding/lerna-lite/tree/main/packages/version) | `npm i @lerna-lite/cli` | create new version for each workspace package | Yes |
| 📰 [publish](https://github.com/ghiscoding/lerna-lite/tree/main/packages/publish) | `npm i @lerna-lite/cli` | publish each workspace package | Yes |
| 🏃 [run](https://github.com/ghiscoding/lerna-lite/tree/main/packages/run) | `npm i @lerna-lite/run` | run npm script in each workspace package | Optional |

**Note:** the default `lerna` CLI is only including 2 built-in commands which are the `publish` and `version`, while `run` command is optional and must be installed separately.

```bash
# publish/version commands CLI
npm install @lerna-lite/cli
# Lerna CLI which includes publish/version commands
npm install @lerna-lite/cli # OR yard add @lerna-lite/cli

# run command CLI
npm install @lerna-lite/run
# optional run command
npm install @lerna-lite/run # OR yarn add @lerna-lite/run
```
**Note:** the `ws-roller` CLI only has 2 commands available `publish` and `version`, while `ws-runner` CLI has the `run` command.

### Usage
Add the following NPM Scripts or simply run the following NodeJS command in your shell.
Add custom NPM Scripts or simply run the following NodeJS commands in a shell.
```js
// package.json / npm scripts
"scripts": {
"roll-version": "ws-roller version",
"roll-publish": "ws-roller publish from-package"
"new-version": "lerna version",
"new-publish": "lerna publish from-package",
"run-tests": "lerna run test", // optional `run` command
}
```

### Configuration
This lib requires a config file in order to do its job properly. It could come from a separate config file in the root (read [`lerna.json` - Wiki](https://github.com/ghiscoding/lerna-lite/wiki/lerna.json) OR a `"lerna": {}` property directly under your `package.json`.

#### Command Options
- `ws-roller`
- [version](https://github.com/ghiscoding/lerna-lite/blob/main/packages/version/README.md)
- [publish](https://github.com/ghiscoding/lerna-lite/blob/main/packages/publish/README.md) (make sure to double-check your [publishConfig](https://docs.npmjs.com/cli/v6/configuring-npm/package-json#publishconfig) access of each package before publishing)
- `ws-runner`
- [run](https://github.com/ghiscoding/lerna-lite/blob/main/packages/run/README.md)

### Migration for [Lerna](https://github.com/lerna/lerna) Users
If you are migrating from Lerna, it is pretty easy and you have to do the following steps to use Lerna-Lite
1. remove Lerna from your dependencies
If you are migrating from Lerna, it should be fairly easy to just replace Lerna with Lerna-Lite and that should be it, the CLI commands are the same, take a look at the quick steps below:
1. remove Lerna from your local & global dependencies
```sh
npm uninstall lerna # OR yarn remove lerna
npm uninstall -g lerna # OR yarn global remove lerna
```
2. install Lerna-Lite CLI(s)
2. install Lerna-Lite CLI to get `version` and `publish` commands
- `run` command is optional and can be installed separately as shown below
```sh
# ws-roller CLI (version/publish commands)
# Lerna CLI (`version`/`publish` commands)
npm install @lerna-lite/cli

# ws-runner CLI (run command)
# optionally install the `run` command
npm install @lerna-lite/run
```
3. change your npm scripts `lerna <command>` to `ws-roller` (or `ws-runner`)
```diff
- "roll-version": "lerna version",
+ "roll-version": "ws-roller version",

- "roll-publish": "lerna publish from-package"
+ "roll-publish": "ws-roller publish from-package"

- "build": "lerna run build"
+ "build": "ws-runner run build"
```

### Development / Contributions
If you wish to contribute to the project, follow these steps
1. install with NPM
```sh
npm install
```
2. you can troubleshoot/debug the code the launch configs that are already defined
3. add/run Jest unit tests
```sh
npm run jest # or npm run jest:watch
```

## Need your Help
Anyone willing to help, please create a Pull Request, really any type of PRs are welcome. 👷👷‍♀️

Also please note that I'm just a simpler developer & user of this lib, the same as you are, my knowledge of the library is also probably similar to yours, but together we can make it better (and lighter).
If you wish to contribute to the project, please follow these steps
1. clone the lib:
- `git clone https://github.com/ghiscoding/lerna-lite`
2. install with NPM:
- `npm install`
3. add/run Jest unit tests:
- `npm run jest # OR npm run jest:watch`
4. you can troubleshoot/debug the code via the VSCode debugger launch configs that are already setup

## Contributions
Feel free to contribute any Pull Request, PRs are very welcome. 👷👷‍♀️

Also please note that I'm just a simple developer & user of this lib, the same as you are, my knowledge of the library is also probably similar to yours but together we can make it better (and lighter).

## Troubleshooting
If you have problems running the lib and your problems are with Git then you should first try the `--git-dry-run` option to see if that helps in finding the error. Another great, and possibly much more useful suggestion, is to search in the Lerna [issues](https://github.com/lerna/lerna/issues) because most of the code came from that library. Lastly if it that is not enough and you wish to troubleshoot yourself, then read this [Troubleshooting - Wiki](https://github.com/ghiscoding/lerna-lite/wiki/Troubleshooting)
78 changes: 0 additions & 78 deletions helpers/command-runner.ts

This file was deleted.

70 changes: 70 additions & 0 deletions helpers/command-runner/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
"use strict";

const path = require("path");
const lernaCLI = require("../../packages/cli/src/lerna-cli");

module.exports = commandRunner;

/**
* A higher-order function to help with passing _actual_ yargs-parsed argv
* into command constructors (instead of artificial direct parameters).
*
* @param {Object} commandModule The yargs command exports
* @return {Function} with partially-applied yargs config
*/
function commandRunner(commandModule) {
/* eslint-disable import/no-dynamic-require, global-require */
const cmd = commandModule.command.split(" ")[0];

// prime the pump so slow-as-molasses CI doesn't fail with delayed require()
require(path.resolve(require.main.filename, "../.."));

return (cwd) => {
// create a _new_ yargs instance every time cwd changes to avoid singleton pollution
const cli = lernaCLI([], cwd)
.exitProcess(false)
.detectLocale(false)
.showHelpOnFail(false)
.wrap(null)
.command(commandModule);

return (...args) => {
return new Promise((resolve, reject) => {
const yargsMeta = {};

const context = {
cwd,
lernaVersion: "__TEST_VERSION__",
loglevel: "silent",
progress: false,
onResolved: (result) => {
// success resolves the result, if any, returned from execute()
resolve(Object.assign({}, result, yargsMeta));
},
onRejected: (result) => {
Object.assign(result, yargsMeta);
// tests expect errors thrown to indicate failure,
// _not_ just non-zero exitCode
reject(result);
},
};

const parseFn = (yargsError, parsedArgv, yargsOutput) => {
// this is synchronous, before the async handlers resolve
Object.assign(yargsMeta, { parsedArgv, yargsOutput });
};

cli
.fail((msg, err) => {
// since yargs 10.1.0, this is the only way to catch handler rejection
// _and_ yargs validation exceptions when using async command handlers
const actual = err || new Error(msg);
// backfill exitCode for test convenience
yargsMeta.exitCode = "exitCode" in actual ? actual.exitCode : 1;
context.onRejected(actual);
})
.parse([cmd, ...args], context, parseFn);
});
};
};
}
11 changes: 11 additions & 0 deletions helpers/command-runner/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"name": "@lerna-test/command-runner",
"version": "0.0.0-test-only",
"description": "A local test helper",
"main": "index.js",
"private": true,
"license": "MIT",
"dependencies": {
"@lerna/cli": "file:../../core/cli"
}
}
2 changes: 1 addition & 1 deletion lerna.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@
"runDryRun": false
}
}
}
}

0 comments on commit 49d2fa1

Please sign in to comment.