Skip to content

Commit

Permalink
docs: Add docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@kevintyj
kevintyj committed Jun 26, 2024
1 parent 765838b commit d6cb453
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 49 deletions.
5 changes: 5 additions & 0 deletions .changeset/calm-taxis-jam.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@kevintyj/prlint": minor
---

Add ability to pass in body to commit
119 changes: 70 additions & 49 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,14 @@
[![codecov](https://codecov.io/gh/kevintyj/prlint/graph/badge.svg?token=WBT1WWSLF0)](https://codecov.io/gh/kevintyj/prlint)

## Getting started

### Use as a standalone action
Use Prlint with any github repository with the latest release.
Checking out the repository is required to fetch the `commitlint.config.js`

**Sample github actions file using PNPM:**
`prlint.yml`
**Sample github actions file (javascript only, no external dependencies):**

`.github/prlint.yml`
```yaml
name: 📝 Lint PR title
on:
Expand All @@ -32,13 +34,11 @@ jobs:
fetch-depth: 0
- name: 📝Validate PR title with commitlint
uses: kevintyj/prlint@v2
# Optional
# Optional (with default values)
with:
download-dependencies: ignore
body: false
```
The above action only check's out the current repository to fetch the commitlint configuration file.
PNPM and node is used to install necessary dependencies, then config-conventional is used as a default config.
When using the above configuration, `pnpm-lock.yaml` is required. Please use npm and node if `package-lock.json` is used.
## v2 release
Expand All @@ -59,7 +59,66 @@ This means that if the user's config does not have any dependencies, the entire
**See Inputs section for more details on how to set this option**
However, if you wish to still download dependencies as a part of your workflow (recommended with cache enabled), resulting in a file as follows:
However, if you wish to still download dependencies as a part of your workflow (recommended with cache enabled) see [v1 compatibility section](##-v1-support) (Configuration file would look identical with different input options)
**When to use different options**
| Project environment and nature of commitlint config | Recommended method |
|---------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Does not use "extends" or outside dependencies **Recommended** | 'ignore' |
| Does not use "extends" but also contains other outside dependencies | 'ignore' and install dependencies using actions |
| Does use "extends" but no outside dependencies | 'node' when no caching is used 'ignore' and install dependencies using actions when caching is enabled |
| Does use "extends" but also contains other outside dependencies | 'ignore' and install dependencies using actions |
## Inputs
### `download-dependencies`
**Optional** Experimental - use node to download commitlint config dependency (eg. @commitlint/config-conventional) Default : `'ignore'`

Options:
- `'node'` uses node's exec to run a child process to automatically detect the dependency and install from action (may be slower if caching is not enabled in actions) - currently only limited to `@commitlint/config-conventional`
- `'ignore'` expects all dependencies to be added with actions script using a package manager such as npm or pnpm

> Only available in v2

---

### `body`
**Optional** Pass the body of the PR to the commit as the body. Default : `'false'`

Options:
- `'true'` Passes the body and appends the body in Github's default style (`\n\n`)
- `'false'` Ignore body

> Only available in v^2.0.1

---

### `cl-config`
**Optional** Path to commit lint config. Default : `'commitlint.config.js'`

> Removed in v2, Only available in v1.0.0 (v1)

## Outputs
#### `lint-status`
Status of the lint result. Returns `✅ Commitlint tests passed!` if successful and `❌ Commitlint tests failed` if
linter tests fail.
#### `lint-details`
Output of the commitlint result.

## Limitations
The current action of Prlint only accepts javascript based configurations on commitlint.
`v1.0.1` introduced support for ESM based configuration files. `v1.1.0` introduced support for custom config file names.
However, due to ESM support added in `v1.0.1` non `js` config files such as `yaml` or `json` is not supported.

Even if the project does not use `config-conventional`, the Prlint uses the configuration as a fallback, therefore the
project must contain the `config-conventional` package as a development dependency.

> Above behavior corrected in v2

## v1 support

**Sample github actions file (using pnpm to download dependencies):**

`prlint.yml`
```yaml
Expand All @@ -84,7 +143,7 @@ jobs:
- name: 🌳Setup Node
uses: actions/setup-node@v4
with:
node-version: 22
node-version: 20
cache: pnpm
- name: 🗂️ Get pnpm store directory
Expand All @@ -105,47 +164,9 @@ jobs:
uses: kevintyj/prlint@v2
```

**When to use different options**

| Project environment and nature of commitlint config | Recommended method |
|---------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| Does not use "extends" or outside dependencies **Recommended** | 'ignore' |
| Does not use "extends" but also contains other outside dependencies | 'ignore' and install dependencies using actions |
| Does use "extends" but no outside dependencies | 'node' when no caching is used 'ignore' and install dependencies using actions when caching is enabled |
| Does use "extends" but also contains other outside dependencies | 'ignore' and install dependencies using actions |

### Inputs

#### `download-dependencies`
**Optional** Experimental - use node to download commitlint config dependency (eg. @commitlint/config-conventional) Default : `'ignore'`

Options:
- `'node'` uses node's exec to run a child process to automatically detect the dependency and install from action (may be slower if caching is not enabled in actions) - currently only limited to `@commitlint/config-conventional`
- `'ignore'` expects all dependencies to be added with actions script using a package manager such as npm or pnpm

> Only available in v2
>
#### `cl-config`
**Optional** Path to commit lint config. Default : `'commitlint.config.js'`

> Removed in v2

### Outputs
#### `lint-status`
Status of the lint result. Returns `✅ Commitlint tests passed!` if successful and `❌ Commitlint tests failed` if
linter tests fail.
#### `lint-details`
Output of the commitlint result.

### Limitations
The current action of Prlint only accepts javascript based configurations on commitlint.
`v1.0.1` introduced support for ESM based configuration files. `v1.1.0` introduced support for custom config file names.
However, due to ESM support added in `v1.0.1` non `js` config files such as `yaml` or `json` is not supported.

Even if the project does not use `config-conventional`, the Prlint uses the configuration as a fallback, therefore the
project must contain the `config-conventional` package as a development dependency.

> Above behavior corrected in v2
The above action only check's out the current repository to fetch the commitlint configuration file.
PNPM and node is used to install necessary dependencies, then config-conventional is used as a default config.
When using the above configuration, `pnpm-lock.yaml` is required. Please use npm and node if `package-lock.json` is used.

## Changelog
See [CHANGELOG](CHANGELOG.md) for the release details
Expand Down

0 comments on commit d6cb453

Please sign in to comment.