Skip to content

Commit

Permalink
feat(*): don't release for types docs, style, test
Browse files Browse the repository at this point in the history 
BREAKING CHANGE:
`nlm` will no longer create a patch tag for `docs`, `style` and `test` commits. If your PR only contains these type of commits, it will no longer release a new version.
  • Loading branch information
Andreas Richter committed Jul 31, 2020
1 parent 1f114c0 commit 11665ca
Show file tree
Hide file tree
Showing 7 changed files with 215 additions and 109 deletions.
159 changes: 81 additions & 78 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,90 @@

🎉🏅 Thanks for helping us improve this project! 🙏

This document outlines some of the practices we care about.
This document outlines some practices we care about.
If you have any questions or suggestions about the process,
feel free to [open an issue](#reporting-issues)
.

## How Can I Contribute?

#### Commits & Commit Messages

Please follow the [angular commit message conventions][angular-commits].
We use an automated tool for generating releases
that depends on the conventions to determine the next version and the content of the changelog.
Commit messages that don't follow the conventions will cause `npm test` (and thus CI) to fail.

The short summary - a commit message should look like this:

```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<references>
<BLANK LINE>
<footer>
```

Everything but the first line is optional.
The empty lines between the different parts are required.

* `<type>`: One of the following:

|`<type>`| explanation | version change |
| :----- | :---------- | :-------------: |
| **feat** | Introduces a new feature | minor |
||
| **fix** | A bug fix | patch |
| **perf** | Performance optimizations | patch |
| **refactor** | Changes to the code structure without fixing bugs or adding features | patch |
| **chore** | Changes to the project setup and tools, dependency bumps, house-keeping | patch |
||
| **docs** | Changes to the documentation | none |
| **style** | Cleanup & lint rule fixes. Note that often it's better to just amend the previous commit if it introduced lint errors | none |
| **test** | Fixing existing tests or adding missing ones. Just like with **style**, if you add tests to a feature you just introduced in the previous commit, consider keeping the tests, and the feature in the same commit instead. | none |
* `<subject>`: A [good git commit message subject](http://chris.beams.io/posts/git-commit/#limit-50).
- Keep it brief. If possible the whole first line should have at most 50 characters.
- Use an imperative mood. "Create" instead of "creates" or "created".
- No period (".") at the end.
* `<body>`: Motivation for the change and any context required for understanding the choices made.
Just like the subject, it should use an imperative mood.
* `<scope>`: The scope is optional and specifies the place of your commit. Use `*` for multiple places.
* `<references>`: Any URLs relevant to the PR go here.
Use one line per URL and prefix it with the kind of relationship, e.g. "Closes: " or "See: ".
If you are referencing an issue in your commit body or PR description,
never use `#123` but the full URL to the issue or PR you are referencing.
That way the reference is easy to resolve from the git history without having to "guess" the correct link
even if the commit got cherry-picked or merged into a different project.
* `<footer>`: This part only applies if your commit introduces a breaking change.
It's important this is present, otherwise the **major version** will not increase.
See below for an example.

[angular-commits]: https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commit-message-format

##### Examples

A feature that introduces a breaking change:

```
feat: Support --yes CLI option
For existing projects all prompts can be inferred automatically.
Manual confirmation for each default provides no value in that case.
Closes https://github.com/my/project/issues/123
BREAKING CHANGE: This removes support for interactive password entry.
Users will have to login beforehand.
```

A simple bug fix:

```
fix(search): Handle multi-byte characters in search logic
```

### Reporting Issues

If you find any mistakes in the docs or a bug in the code,
Expand All @@ -29,7 +106,8 @@ If you report a bug, please follow these guidelines:

### Improving Documentation

For small documentation changes, you can use [Github's editing feature](https://help.github.com/articles/editing-files-in-another-user-s-repository/).
For small documentation changes, you can use
[Github's editing feature](https://help.github.com/articles/editing-files-in-another-user-s-repository/).
The only thing to keep in mind is to prefix the commit message with "docs: ".
The default commit message generated by Github will lead to a failing CI build.

Expand All @@ -40,7 +118,7 @@ it might be better to follow the [instructions for contributing code below](#con

**Note:** If you're planning on making substantial changes,
please [open an issue first to discuss your idea](#reporting-issues).
Otherwise you might end up investing a lot of work
Otherwise, you might end up investing a lot of work
only to discover that it conflicts with plans the maintainers might have.

The general steps for creating a pull request are:
Expand Down Expand Up @@ -73,78 +151,3 @@ a few general rules of thumb:
* Actually, if you create helpers you might want to put those into a separate package.
That way it's easier to reuse them.

#### Commits & Commit Messages

Please follow the [angular commit message conventions][angular-commits].
We use an automated tool for generating releases
that depends on the conventions to determine the next version and the content of the changelog.
Commit messages that don't follow the conventions will cause `npm test` (and thus CI) to fail.

The short summary - a commit message should look like this:

```
<type>: <subject>
<body>
<references>
<footer>
```

Everything but the first line is optional.
The empty lines between the different parts are required.

* `<type>`: One of the following:
- **feat:** Introduces a new feature. This will cause the minor version to go up.
- **fix:** A bug fix. Causes a patch version bump.
- **docs:** Changes to the documentation.
This will also cause an increase of the patch version so that the changes show up in the npm registry.
- **style:** Cleanup & lint rule fixes.
Note that often it's better to just amend the previous commit if it introduced lint errors.
- **refactor:** Changes to the code structure without fixing bugs or adding features.
- **perf:** Performance optimizations.
- **test:** Fixing existing tests or adding missing ones.
Just like with **style**, if you add tests to a feature you just introduced in the previous commit,
consider keeping the tests and the feature in the same commit instead.
- **chore:** Changes to the project setup and tools, dependency bumps, house-keeping.
* `<subject>`: A [good git commit message subject](http://chris.beams.io/posts/git-commit/#limit-50).
- Keep it brief. If possible the whole first line should have at most 50 characters.
- Use imperative mood. "Create" instead of "creates" or "created".
- No period (".") at the end.
* `<body>`: Motivation for the change and any context required for understanding the choices made.
Just like the subject, it should use imperative mood.
* `<references>`: Any URLs relevant to the PR go here.
Use one line per URL and prefix it with the kind of relationship, e.g. "Closes: " or "See: ".
If you are referencing an issue in your commit body or PR description,
never use `#123` but the full URL to the issue or PR you are referencing.
That way the reference is easy to resolve from the git history without having to "guess" the correct link
even if the commit got cherry-picked or merged into a different project.
* `<footer>`: This part only applies if your commit introduces a breaking change.
It's important this is present, otherwise the major version will not increase.
See below for an example.

[angular-commits]: https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commit-message-format

##### Examples

A feature that introduces a breaking change:

```
feat: Support --yes CLI option
For existing projects all prompts can be inferred automatically.
Manual confirmation for each default provides no value in that case.
Closes https://github.com/my/project/issues/123
BREAKING CHANGE: This removes support for interactive password entry.
Users will have to login beforehand.
```

A simple bug fix:

```
fix: Handle multi-byte characters in search logic
```

57 changes: 36 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# nlm

A tool for automating the release of libraries in the spirit of [semantic-release](https://github.com/semantic-release/semantic-release).
A tool for automating the release of libraries in the spirit of
[semantic-release](https://github.com/semantic-release/semantic-release).

#### Highlights

Expand All @@ -13,8 +14,11 @@ A tool for automating the release of libraries in the spirit of [semantic-releas

### Prerequisites

1. A Github access token with `repo` scope. This is required for creating version commits, releases, and tagging issues. Github has a instructions for [creating an access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/).
1. A valid repository field in your `package.json`. E.g. `https://github.mycorp.net/myorg/repo.git` or `https://github.com/myorg/repo.git`.
1. A Github access token with `repo` scope. This is required for creating version commits, releases,
and tagging issues. Github has instructions for
[creating an access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/).
1. A valid repository field in your `package.json`. E.g. `https://github.mycorp.net/myorg/repo.git` or
`https://github.com/myorg/repo.git`.
1. The repository field should point to an existing project on Github.

### Install `nlm`
Expand All @@ -26,12 +30,11 @@ A tool for automating the release of libraries in the spirit of [semantic-releas
### Setting up CI

`nlm` will automatically look for well-known environment variables during CI
builds like `CI=true`, `BRANCH=branch-name`, etc..
builds like `CI=true`, `BRANCH=branch-name`, etc.
It should work out-of-the-box for both [Travis](https://travis-ci.org/) and
[DotCI](https://groupon.github.io/DotCi/).

For Github and npm interactions to work,
it requires the following additional environment variables:
For Github and npm interactions to work, it requires the following additional environment variables:

* `GH_TOKEN`: The access token from above.
* `NPM_TOKEN`: An npm access token. You can find this in `~/.npmrc` as `_authToken`.
Expand All @@ -44,13 +47,15 @@ All tokens and passwords should be set up as encrypted environment variables.

#### Travis

For Travis you can follow the [official Travis docs](https://docs.travis-ci.com/user/environment-variables/#Encrypted-Variables):
For Travis, you can follow the
[official Travis docs](https://docs.travis-ci.com/user/environment-variables/#Encrypted-Variables):

```bash
travis encrypt GH_TOKEN=your_github_token --add env
```

If you want to publish from CI, you can either use the [official Travis feature](https://docs.travis-ci.com/user/deployment/npm/) or `nlm` itself.
If you want to publish from CI, you can either use the
[official Travis feature](https://docs.travis-ci.com/user/deployment/npm/) or `nlm` itself.
The latter gives you support for managing different `dist-tag`s based on branches.

If you want to use `nlm` to publish, you'll have to add `NPM_TOKEN`:
Expand All @@ -61,12 +66,14 @@ travis encrypt NPM_TOKEN=your_npm_token --add env

#### DotCI

DotCI lacks native support for encrypted environment variables.
But the [EnvInject Plugin](https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin) provides an option called "Inject passwords to the build as environment variables" which can fill the same role.
DotCI lacks native support for encrypted environment variables. But the
[EnvInject Plugin](https://plugins.jenkins.io/envinject/) provides an option called
"Inject passwords to the build as environment variables" which can fill the same role.

You should also enable builds of pull requests for pushes against the same repository. Otherwise the automated tagging of PRs won't work.
You should also enable builds of pull requests for pushes against the same repository. Otherwise, the
automated tagging of PRs won't work.

Finally enable publishing by adding the following to `.ci.yml`:
Finally, enable publishing by adding the following to `.ci.yml`:

```yaml
build:
Expand All @@ -88,22 +95,28 @@ Most `nlm` configuration happens via native npm options in `package.json`:
In most cases these settings are enough to make `nlm` do the right thing.
For more customization, you can use `.nlmrc` or an `nlm` section in `package.json`:

* `channels`: A map of branch name to npm `dist-tag`. When publishing, this will determine what will be published and how it's tagged. By default there's one entry in this map: `{ master: 'latest' }`. Which means that a publish from `master` updates the `latest` tag and publish from any other branch does nothing.
* `hooks`: A map of hook names to shell commands. When executing any of the [commands](#commands) listed below some of these hooks will get triggered. The available hooks are:
* `channels`: A map of branch name to npm `dist-tag`. When publishing, this will determine what
will be published and how it's tagged. By default, there's one entry in this map: `{ master: 'latest' }`.
Which means that publishing from `master` updates the `latest` tag and publishing from any other branch
does nothing.
* `hooks`: A map of hook names to shell commands. When executing any of the [commands](#commands)
listed below some of these hooks will get triggered. The available hooks are:

Hook | Description
--------- | -----------
`prepare` | Called when the release is about to be prepared. This is before updating files such as package.json, CHANGELOG.md and pushing a commit. It provides a reference to the **next version** number via the environment variable **NLM_NEXT_VERSION**.
`prepare` | Called when the release is about to be prepared. This is before updating files such as
package.json, CHANGELOG.md and pushing a commit. It provides a reference to the **next version** number
via the environment variable **NLM_NEXT_VERSION**.

* `license.files`: List of files and/or directories to add license headers to.
* `license.exclude`: List of files to exclude that would otherwise be included. `nlm` will always exclude anything in `node_modules`.
* `license.exclude`: List of files to exclude that would otherwise be included. `nlm` will always exclude
anything in `node_modules`.
* `acceptInvalidCommits`: Accept commit messages even if they can't be parsed.
It's highly discouraged to use this option.
In this mode any commit with an invalid commit message will be treated as "semver-major".
* `deprecated`: String (may be empty) describing reason this package has been
deprecated. To deprecate a package, set it to a descriptive reason.
To "un-deprecate" a package, set it to an empty string (can then be
later deleted).
To "un-deprecate" a package, set it to an empty string (can then be later deleted).

If there's no file named `LICENSE` in the repository, `nlm` won't attempt to add the headers.

Expand All @@ -129,11 +142,12 @@ Verify that the current state is valid and could be released.
Will also add license headers where they are missing.

1. Everything `nlm verify` does.
1. If `hooks#prepare` is present in the `nlm` section of the `package.json`, the shell command defined by the hook will be executed.
1. If `hooks#prepare` is present in the `nlm` section of the `package.json`, the shell command defined by
the hook will be executed.
1. If there are unreleased changes:
1. Create a new CHANGELOG entry and update `package.json#version`.
1. Commit and tag the release.
1. Push the tag and the release branch (e.g. master).
1. Push the tag, and the release branch (e.g. master).
1. Create a Github release.
1. Publish the package to npm or update `dist-tag` if required.

Expand All @@ -147,5 +161,6 @@ and nlm tries to not make any assumptions about how people might interpret those

### `nlm changelog`

Preview the changelog that would be generated by the commits between the last version tag and the current `HEAD`.
Preview the changelog that would be generated by the commits between the last version tag and the
current `HEAD`.
If there are no unreleased commits, the output will be empty.
12 changes: 6 additions & 6 deletions lib/steps/release-info.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ const INVALID_COMMITS_MESSAGE = [
'[2] https://git-scm.com/docs/git-rebase',
].join('\n');

const RELEASE_TYPES = ['none', 'patch', 'minor', 'major'];

function formatInvalidCommit(commit) {
return `* [${commit.sha.slice(0, 7)}] ${commit.header}`;
}
Expand All @@ -78,8 +80,6 @@ function isBreaking(note) {
return note.title.startsWith('BREAKING CHANGE');
}

const RELEASE_TYPES = ['none', 'patch', 'minor', 'major'];

function determineReleaseInfo(commits, acceptInvalidCommits) {
let releaseType = 0;
const invalidCommits = [];
Expand All @@ -94,12 +94,8 @@ function determineReleaseInfo(commits, acceptInvalidCommits) {

switch (commit.type) {
case 'chore':
case 'doc':
case 'docs':
case 'fix':
case 'refactor':
case 'style':
case 'test':
case 'perf':
releaseType = Math.max(releaseType, 1);
break;
Expand All @@ -108,6 +104,10 @@ function determineReleaseInfo(commits, acceptInvalidCommits) {
releaseType = Math.max(releaseType, 2);
break;

case 'doc':
case 'docs':
case 'style':
case 'test':
case 'pr':
continue;

Expand Down
9 changes: 9 additions & 0 deletions test/fixtures/minor-commits
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
#!/usr/bin/env bash
set -e
git init

git checkout -b minor-commits

echo "console.log('more');" > feat.js
git add feat.js
git commit -m "feat: Adding feat commit"
17 changes: 17 additions & 0 deletions test/fixtures/patch-commits
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
#!/usr/bin/env bash
set -e
git init

git checkout -b patch-commits

echo "console.log('more');" > chore.js
git add chore.js
git commit -m "chore: Adding chore commit"

echo "console.log('more');" > refactor.js
git add refactor.js
git commit -m "chore: Adding refactor commit"

echo "console.log('more');" > perf.js
git add perf.js
git commit -m "chore: Adding perf commit"
Loading

0 comments on commit 11665ca

Please sign in to comment.