Skip to content

Commit

Permalink
docs: updating
Browse files Browse the repository at this point in the history
  • Loading branch information
@lvjiaxuan
lvjiaxuan committed Feb 27, 2024
1 parent 5ac5561 commit 3a29781
Showing 1 changed file with 51 additions and 45 deletions.
96 changes: 51 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,61 +2,70 @@

![actions](https://github.com/lvjiaxuan/release/actions/workflows/ci.yml/badge.svg) [![npm](https://img.shields.io/npm/v/lvr)](https://www.npmjs.com/package/lvr)

Do the releasing flows such as:
1. Bump version in different strategy. Support monorepo.
2. Generate `CHANGELOG.md` based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
Perform jobs related to the release flows, such as:
1. Bump version.
2. Generate `CHANGELOG.md`.
3. Commit / Tag / Push.
4. Create a release and publish on GitHub Action might be more efficient.
4. Create a release and publish node packages.

## Features

1. One script usage, may be opinionated, meaning it is not very customizable.
2. Generate a tag range changelog.
1. One brief script is good to go, may be a little opinionated by default options.
2. Generate a tag-ranged `CHANGELOG.md`.
3. Publish job supports sync to cnpm.

## Usage

Perform Bump :point_right: CHANGELOG :point_right: Commit :point_right: Tag :point_right: Push in one script:
```sh
npx lvr
```

# Support the dry run to confirm what will be executed.
# npx lvr --dry
Use the dry run option to confirm what will be executed:
```sh
# npx lvr --dry-run
npx lvr -d
```

Install globally.
Install globally:
```sh
npm i lvr -g
```

Check more CLI options.
More options detail:
```sh
lvr -h
```

### Bump
### Commands used separately.

#### Bump

Powered by [conventional-recommended-bump](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump) and [semver](https://github.com/npm/node-semver). Using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) preset by default.

Bump `package.json` in the root:
```sh
# If a monorepo, it would bump those changed packages by default.
# lvr bump
lvr b
```

#### options
> In a detected monorepo, it would bump those changed packages by default.
##### options

In a detected monorepo, it would bump all packages whether they are changed.
If the root package.json has the `version` field, packages would be bumped to the same version based on it.
```sh
# In a detected monorepo, it would bump all packages whether they are changed.
lvr b --all
```

In a detected monorepo, `--pkg` helps to prompt which packages should be bumped:
```sh
# In a detected monorepo, `--pkg` helps to prompt which packages should be bumped.
lvr b --pkg
```

Bump to the specified semver increment level rather than depending on `conventional-recommended-bump`.
```sh
# Bump to the specified semver increment level rather than depending on `conventional-recommended-bump`.
lvr b --major
lvr b --major --all
lvr b --major --pkg
Expand All @@ -70,25 +79,25 @@ Semver increment level support:
- `--prepatch`: bump as a semver-prepatch version, can set id with string.
- `--prerelease`: bump as a semver-prerelease version, can set id with string.

In a detected monorepo, when releasing only one package, it specifies the tag name as `vx.x.x` instead of `abc@x.x.x`:
```sh
# In a detected monorepo, when releasing only one package, it specifies the tag name as `vx.x.x` instead of `abc@x.x.x`.
lvr b --main-pkg
```

### Changelog
#### Changelog

Powered by [antfu/changelogithub](https://github.com/antfu/changelogithub) and [unjs/changelogen](https://github.com/unjs/changelogen).

Generate `CHANGELOG.md` with all existing tags:
```sh
# Generate CHANGELOG with all existing tags.
# lvr changelog
lvr c
```

#### options
##### options

```sh
# generate within a tag range.
# within a tag range.
lvr changelog --tag=v1.0.1...v2.1.3

# to last 2 tag.
Expand All @@ -98,40 +107,37 @@ lvr changelog --tag==2
lvr changelog --tag=v0.0.2
```

It means that the `CHANGELOG.md` would contain more commits that were not be parsed by `conventional commits`. Disable by default.
```sh
# It means that CHANGELOG.md would contain more changes that were not be parsed by `conventional commits`.
# Disable by default.
lvr changelog --verbose
```

#### About author

To be able to generate the format of `@authorName` for the interaction in the GitHub's release note, I need to fetch the GitHub Rest API. However, it occurred to me that the API has a [rate limit](https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting) for an IP.

So we have to pass a [GitHub PAT](https://github.com/settings/tokens?type=beta) by `--token` when encountering this situation 😔.

Alternatively, we can also create a `.env.local` file which should be included in the `.gitignore` .
```env
GITHUB_TOKEN = your-github-pat
```

### Commit / Tag / Push
> [!NOTE]
> **About author**
>
> To be able to generate the format of `@authorName` for the interaction in the GitHub's release note, I need to fetch the GitHub Rest API. However, it occurred to me that the API has a [rate limit](https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting) for an IP.
>
> So we have to pass a [GitHub PAT](https://github.com/settings/tokens?type=beta) by `--token` when encountering this situation 😔.
>
> Alternatively, we can also create a `.env.local` file which should be included in the `.gitignore` .
> ```env
> # .env.local
> GITHUB_TOKEN = your-github-pat
> ```
#### Commit / Tag / Push

Enable `--commit` `--tag` `--push` when execute the `lvr` script without other command. (opt-out like `--no-push`, etc.)

> `--no-changelog` is considered to enable these git jobs in the same way, while `--no-bump` makes no sense to the further step.
Use `Release {r}` as the default commit message. The placeholder `{r}` will be replaced by the tag name from the bumped result. If multiple packages are released in the same commit, the `human-id` library is utilized to create words for the commit message and tag name:
```sh
# Use `Release {r}` as commit message by default.
# The `{r}` placeholder would be replaced by the committed tag name from bumped result.
# When multiple packages were released at same commit, the `human-id` library is used to generate words that serve as commit message and tag name.
# Customizable.
lvr --commit="R: {r}"
```

```sh
# Use the committed tag name from bumped result from package.json by default.
# Customizable.
# Use the tag name from bumped result from package.json by default:
lvr --tag=BatMan

# Push current branch and new tag by default.
Expand All @@ -144,15 +150,15 @@ lvr --push=branch
lvr --push=tag
```

> **Note**
> [!NOTE]
> It is not recommended to release more than one package at the same time in order to ensure a concise commit message and tag name.
### Send a GitHub Release on *GitHub Action*
### Send a GitHub Release on CI

See [yml.ts](./src/command/yml.ts). And modify on your own.
See [yml.ts](./src/command/yml.ts) and modify on your own.

```sh
# Add a workflow file at `.github/workflows/lvr.yml`.
# Add a workflow file to `.github/workflows/lvr.yml`.
lvr yml
```

Expand Down

0 comments on commit 3a29781

Please sign in to comment.