Skip to content

Commit

Permalink
docs: create project's documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@lekterable
lekterable committed Jul 23, 2021
1 parent b80d365 commit 04cf235
Show file tree
Hide file tree
Showing 7 changed files with 301 additions and 237 deletions.
245 changes: 8 additions & 237 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,254 +27,25 @@

## Intro

**perfekt** is a release, changelog and versioning manager. It is easy to use and doesn't require any configuration to get it up and running.
**perfekt** is a release, changelog and versioning manager. It's easy to use and doesn't require any configuration to get it up and running.

## Installation
## Convention

`npm i -g perfekt`
For **perfekt** to run with its full power, your project must follow the [conventional commits](https://www.conventionalcommits.org) specification, this allows it to know the type of changes introduced in a given commit.

Installing **perfekt** globally is recommended as this will allow you to conveniently use it on different projects.
If your project doesn't do it yet, you can start any time as there is no need for rewriting any git history, simply create an initial release which will contain all of the _unconventional_ commits and after that start naming your commits accordingly.

If you'd like to use it as a git hook or integrate it into your CI/CD you can also install it locally.

## Prerequisites

For **perfekt** to run with its full power, your project must follow [conventional commits](https://www.conventionalcommits.org) specification, this makes it possible to know what type of changes were introduced in a given commit and categorize it.

If your project is not following this convention, you can start any time as there is no need to rewrite the git history, simply create an initial release that will contain all the "legacy" commits and after that start naming your commits accordingly.
If for some reason you can't follow the convention for your commits' names, you can still use **perfekt** but you will lose some of the features, like grouping the commits by type or ability to automatically determine the next release version based on unreleased changes using `new` keyword in the `perfekt release new` command, about which you can read more [here](https://lekterable.github.io/perfekt/#/documentation?id=release).

## Getting started

How to get started, depends mostly on your needs and also on your project's state.

If you're not interested in executing a release, and just want to generate a changelog, go to [changelog documentation](#changelog)

If your project is fairly new, go ahead and start with the [new projects section](#new-projects), if it is in development for some time already AND it has a lot (and I mean A LOT) of commits, proceed to the [old projects section](#old-projects).

### New projects

For the new projects, all you need to do is to make sure that you don't have any leftover git tags that could cause a problem, to confirm that, run:

`git tag`

If the output is empty, you should be able to run:

`perfekt release <version>`

where `<version>` is the version of your new release

refer to [release documentation](#release) for more information

### Old projects

For the projects that have a long-existing git history, which could potentially make the process time out, you can use:

`perfekt release <version> --from <commit>`

where `<version>` is the version of your new release and `<commit>` is the hash of the last commit that should **NOT** be the part of the release.

after this, you can start referring to [new projects section](#new-projects) when executing future releases.

## Documentation

For the list of available commands you can always run:

`perfekt help`

### `init` [WIP]

Usage: `perfekt init [options]`

Starts an initialization process and generates an empty configuration file.

Options:

`-h, --help` - display help for command

### `release`

Usage: `perfekt release [options] <version>`

Executes a release

This will:

- Update the version in your `package.json` and `package-lock.json`
- Generate and save the [changelog](#changelog) using passed `version`
- Create a release commit with the changes in your `package.json`, `package-lock.json` and `CHANGELOG.md`
- Create a git tag

Options:

`-h, --help` - display help for command

`--from <commit>` - SHA of the last commit which will **NOT** be included in this release

Arguments:

`version` - _(required)_ version which will be used while executing the release. You can use `major`, `minor` and `patch` instead of a specific version number to bump it or `new` to make **perfekt** determine the version for you automatically based on the unreleased changes.

### `changelog`

Usage: `perfekt changelog [options] [version]`

Generates changelog

This will:

- Look for the latest git tag
- if found transform unreleased into a release and append with the previous changelog
- if **NOT**, try to generate a new changelog for the whole history
- Output changelog in the console, if you want to save it in the `CHANGELOG.md` file use `--write` option

Options:

`-h, --help` - display help for command

`--write` - write the output to file

`--root` - generate changelog for the entire history

`--from <commit>` - SHA of the last commit which will **NOT** be included in this changelog

Arguments:

`version` - _(optional)_ version which will be used for generating the changelog, fallbacks to [unreleased format](#unreleasedHeader) if not passed

## Configuration

**perfekt's** huge advantage is it's configurability.

See [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for more details on what configuration formats are supported.

Default config looks like this:

```json
{
"unreleasedHeader": "# Latest",
"releaseHeader": "# %version%",
"breakingHeader": "## BREAKING",
"groups": [
{
"name": "## Features",
"change": "minor",
"aliases": ["feat", "feature"]
},
{
"name": "## Fixes",
"change": "patch",
"aliases": ["fix"]
}
],
"miscFormat": "## Misc",
"lineFormat": "- %message% %hash%",
"ignoredScopes": ["changelog"]
}
```

### `unreleasedHeader`

Format of the unreleased-block header in the generated changelog

Placeholders:

none

Default:

`# Latest`

### `breakingHeader`

Format of the breaking changes header in the generated changelog

Placeholders:

none

Default:

`## BREAKING`

### `releaseHeader`

Format of the release header in the generated changelog

Placeholders:

`%version%` - release version

Default:

`# %version%`

### `groups`

Used to define how commits should be grouped inside of the release block.

Each object is a separate group, e.g:

```json
{
"name": "## Features",
"change": "minor",
"types": ["feat", "feature"]
}
```

The `name` property will be used as the group's header in changelog, `change` is needed to determine the release type when using `new` as a release version and the `types` array contains all commit types which should be associated with that group.

All commits with unmatched types will become a part of the `Misc` group.

> commit type comes from: `type(scope?): message`
Default:

`[ { name: '## Features', change: 'minor', types: ['feat', 'feature'] }, { name: '## Fixes', change: 'patch', types: ['fix'] } ]`

> change can be either `major`, `minor` or `patch`
> `Breaking` and `Misc` groups correspond to `major` and `patch` changes respectively.
### `miscFormat`

Format of the miscellaneous header in the generated changelog

Placeholders:

none

Default:

`## Misc`

### `lineFormat`

Format of the individual lines in the generated changelog

Placeholders:

`%message%` - commit message

`%hash%` - abbreviated (8-digit long) commit hash

`%HASH%` - full commit hash

Default:

`- %message% %hash%`

### `ignoredScopes`

Array of scopes which will be ignored while generating a changelog

Default:
For a quick introduction and set up instructions head to the [getting started](https://lekterable.github.io/perfekt/#/getting-started.md) section.

`['changelog']`
You can also view the entire documentation online at [lekterable.github.io/perfekt](https://lekterable.github.io/perfekt)

## Badge

Want to let everyone know that your project is under a _**perfekt**_ management?
Would you like to let the whole world know that your project is under the _**perfekt**_ management?

[![management: perfekt👌](https://img.shields.io/badge/management-perfekt👌-red.svg?style=flat-square)](https://github.com/lekterable/perfekt)

Expand Down
Empty file added docs/.nojekyll
View file
Empty file.
4 changes: 4 additions & 0 deletions docs/_sidebar.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
- [Intro](/)
- [Getting started](getting-started.md)
- [Documentation](documentation.md)
- [Configuration](configuration.md)
Loading

0 comments on commit 04cf235

Please sign in to comment.