Skip to content

Commit

Permalink
feat: .changescriberc
Browse files Browse the repository at this point in the history
  • Loading branch information
giovanni-bertoncelli committed Feb 21, 2024
1 parent 8af4a66 commit b7f9676
Show file tree
Hide file tree
Showing 22 changed files with 1,967 additions and 1,341 deletions.
41 changes: 24 additions & 17 deletions .eslintrc.js
Original file line number Diff line number Diff line change
@@ -1,19 +1,26 @@
module.exports = {
"env": {
"browser": true,
"es6": true
},
"extends": [
"airbnb-base"
],
"globals": {
"Atomics": "readonly",
"SharedArrayBuffer": "readonly"
},
"parserOptions": {
"ecmaVersion": 2018,
"sourceType": "module"
},
"rules": {
env: {
browser: false,
commonjs: true,
es2021: true
},
extends: 'standard',
overrides: [
{
env: {
node: true
},
files: [
'.eslintrc.{js,cjs}'
],
parserOptions: {
sourceType: 'script'
}
}
};
],
parserOptions: {
ecmaVersion: 'latest'
},
rules: {
}
}
177 changes: 102 additions & 75 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,58 @@
| ![changelogger logo](./changelogger.jpeg) |
| ![changescribe logo](./changescribe.jpeg) |
| :---------------------------------------: |
| *changelogger 𐫴 generated by AI* |
| *changescribe 𐫴 generated by AI* |

# @ctinnovation/changelogger
# changescribe

A CHANGELOG.md utility generator. Provide a folder `/unreleased` with a Markdown file for each of your completed tasks: each file should be named with the task or ticket code related.

Run this utility in order to generate or update a CHANGELOG file merging each file in a new release or explore a range of versions included in the CHANGELOG. You must specify the [semver version](https://semver.org/lang/it/) code for the next release to be generated.

- [Installation](#installation)
- [Configuration](#configuration)
- [Commands and usage](#commands-and-usage)
- [Generate (default)](#generate-default)
- [Task file format](#task-file-format)
- [Example](#example)
- [Explore](#explore)
- [Init](#init)
- [Task file format](#task-file-format)
- [Example](#example)

## Installation

This tool needs [NodeJS](https://nodejs.org/en) and it is tested with node version `16 ~ 20.X`.

```bash
npm install -g @ctinnovation/changelogger
changelogger --help
npm install -g @ctinnovation/changescribe
changescribe --help
```

### Configuration

You can configure this utility by using the inline CLI arguments illustrated below (EG: `--targetVersion 1.1.0`) or by creating a file `.changescriberc` in the root path you will run this tool into.

When using a `.changescriberc` file (default JSON or alternately CommonJS using extension `.js` or `.cjs`) you can specify the default values to use for each available command:

```json
{
"generate": {
"fromPackageJson": true,
"targetVersion": "1.1.1"
},
"init": {
"output": "/test/CHANGELOG.md"
},
"explore": {
"output": "console"
}
}
```

Once you run `changescribe` the arguments defaults will be resolved in this order of priority:

1. Command defaults (the defaults value illustrated by executing `changescribe --help`)
2. `.changescriberc(.c?js)?` values, if the file exists
3. Inline CLI arguments passed (EG: `changescribe --targetVersion 1.1.0`)

## Commands and usage

### Generate (default)
Expand All @@ -49,19 +77,19 @@ In your `unreleased` folder you have a `PR-120.md` file with this content:
Running this utility:

```bash
changelogger --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} --targetVersion 1.0.0
changescribe --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} --targetVersion 1.0.0
```

or

```bash
changelogger generate --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} --targetVersion 1.0.0
changescribe generate --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} --targetVersion 1.0.0
```

or (use package.json version as target version)

```bash
changelogger generate --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} -p
changescribe generate --taskUrlTemplate http://mydomain.atlassian.net/browse/{taskCode} -p
```

You'll have a CHANGELOG.md like this:
Expand Down Expand Up @@ -95,30 +123,71 @@ You'll have a CHANGELOG.md like this:

Feel free to customize your template by modifying the templates inside `templates` folder.

| Argument | Description | Value |
| ------------------------ | ------------------------------------------------------------------ | ---------------------------------------------- |
| --version | Show version number | [boolean] |
| -t, --targetVersion | Specific target version. | [string] |
| -p, --fromPackageJson | Retrieve target version from pkg.json (excludes `--targetVersion`) | [boolean] [default: false] |
| -o, --output | Ouput CHANGELOG file | [string] [default: process.pwd()/CHANGELOG.md] |
| -i, --input | Input folder for compiling the changelog | [string] [default: process.pwd()/unreleased] |
| --includeCommits | Include branch commits in new release | [boolean] [default: false] |
| --excludeTaskList | Exclude tasks list after release title | [boolean] [default: false] |
| --createOutputIfNotFound | Create a new output file if not found | [boolean] [default: true] |
| -u, --taskUrlTemplate | Associated task URL | [string] [required] |
| --help | Show help | [boolean] |
| Argument | Description | Value |
| ------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------- |
| -t, --targetVersion | Specific target version. *Mandatory if no `--fromPackageJson` specified* | [string] |
| -p, --fromPackageJson | Retrieve target version from pkg.json *(overrides `--targetVersion`)* | [boolean] [default: false] |
| -o, --output | Ouput CHANGELOG file | [string] [default: process.pwd()/CHANGELOG.md] |
| -i, --input | Input folder for compiling the changelog | [string] [default: process.pwd()/unreleased] |
| --includeCommits | Include branch commits in new release | [boolean] [default: false] |
| -u, --taskUrlTemplate | Associated task URL template. *Mandatory if `--excludeTaskList` is false* | [string] [required] |
| --excludeTaskList | Exclude tasks list after release title | [boolean] [default: false] |
| --createOutputIfNotFound | Create a new output file if not found | [boolean] [default: true] |
| --version | Show version number | [boolean] |
| --help | Show help | [boolean] |

#### Task file format

For the `generate` command you must provide a Markdown file for each of yours task completed on the current branch. Each file:

- Should be named with the code of the task
- Should be splitted in sections with these titles:
- If anything changed:
- `## Change[d]`
- `## Edit[ed]`
- `## Update[d]`
- If anything was fixed/hotfixed:
- `## [hot]Fix[ed]`
- If anything was added:
- `## Add[ed]`
- `## Create[d]`
- If anything was removed:
- `## Remove[d]`
- `## Cancel[led]`
- If anything was refactored
- `## Refactor[ed]`

> The `[notation]` used here indicates optional group of characters inside the section title. Each possible variation will be standardised to the form: Changed, Added, Removed, Fixed
- Each section should list each change prepended with `-`.
- If anything in your list is a breaking change you can prepend your list with `[breaking]`


> 🔥 The CHANGELOG format inspires to [keepachangelog](https://keepachangelog.com/it-IT/1.0.0/)
##### Example

```markdown
## Changed
- change 1
- change 2
- [breaking] breaking change 3!

## Fix
- fix 1
- fix 2
```

### Explore

You can explore a range of versions contained in a `CHANGELOG.md` file generated with this tool:
With `changescribe explore` can explore a range of versions contained in a `CHANGELOG.md` file generated with `changescribe`:

```bash
changelogger explore --range 1.2.1
changescribe explore --range 1.2.1
```

This command will exctract you a range of versions, in this case from 1.2.1 to the latest.
You'll get a console logs similar to the following:
You'll get a console log similar to the following:

---
> # `packageName` changelog from 1.2.1 to 1.3.1 (1.2.1~1.3.1)
Expand Down Expand Up @@ -155,66 +224,24 @@ You'll get a console logs similar to the following:
>
---

| Argument | Description | Value |
| ------------ | ------------------------------------------------ | --------------------------------------------- |
| --version | Show version number | [boolean] |
| -r, --range | Range of versions in a format like X.Y.Z ~ A.B.C | [string] [required] |
| -o, --output | Output path | [string] [default: "console"] |
| -i, --input | Input CHANGELOG for explore diffs | [string] [default:process.pwd()/CHANGELOG.md] |
| --help | Show help | [boolean] |
| Argument | Description | Value |
| ------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| --version | Show version number | [boolean] |
| -r, --range | Range of versions in a format like X.Y.Z ~ A.B.C | [string] [required] |
| -o, --output | Output path. If not `console` you can specify a path which the resulting Markdown will be saved into | [string] [default: "console"] |
| -i, --input | Input CHANGELOG for explore diffs | [string] [default:process.pwd()/CHANGELOG.md] |
| --help | Show help | [boolean] |

### Init

Creates a new empty CHANGELOG.md file.

```bash
changelogger init
changescribe init
```

| Argument | Description | Value |
| ------------ | -------------------- | --------------------------------------------- |
| --version | Show version number | [boolean] |
| -o, --output | Ouput CHANGELOG file | [string] [default:process.pwd()/CHANGELOG.md] |
| --help | Show help | [boolean] |

## Task file format

For the `generate` command you must provide a Markdown file for each of yours task completed on the current branch. Each file:

- Should be named with the code of the task
- Should be splitted in sections with these titles:
- If anything changed:
- `## Change[d]`
- `## Edit[ed]`
- `## Update[d]`
- If anything was fixed/hotfixed:
- `## [hot]Fix[ed]`
- If anything was added:
- `## Add[ed]`
- `## Create[d]`
- If anything was removed:
- `## Remove[d]`
- `## Cancel[led]`
- If anything was refactored
- `## Refactor[ed]`

> The `[notation]` used here indicates optional group of characters inside the section title. Each possible variation will be standardised to the form: Changed, Added, Removed, Fixed
- Each section should list each change prepended with `-`.
- If anything in your list is a breaking change you can prepend your list with `[breaking]`


> 🔥 The CHANGELOG format inspires to [keepachangelog](https://keepachangelog.com/it-IT/1.0.0/)
### Example

```markdown
## Changed
- change 1
- change 2
- [breaking] breaking change 3!

## Fix
- fix 1
- fix 2
```
6 changes: 3 additions & 3 deletions cli.js
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
#!/usr/bin/env node
const yargs = require('yargs');
const yargs = require('yargs')
const { argv } = yargs
.usage('Utilizzo: node $0 <command> [options]')
.command(require('./commands/init'))
.command(require('./commands/explore'))
.command(require('./commands/generate'))
.demandCommand()
.argv;
.argv

module.exports = argv;
module.exports = argv
41 changes: 25 additions & 16 deletions commands/explore/argv.js
Original file line number Diff line number Diff line change
@@ -1,41 +1,50 @@
const path = require('path');
const fs = require('fs');
const path = require('path')
const fs = require('fs')
const { loadDefaultsFromFile } = require('../../helpers/defaults')

const argvBuilder = function argvBuilder(yargs) {
const COMMAND_DEFAULTS = {
input: path.resolve(process.cwd(), './CHANGELOG.md'),
output: 'console'
}

const argvBuilder = function argvBuilder (yargs) {
const defaults = loadDefaultsFromFile('explore', COMMAND_DEFAULTS)
yargs
.example(
'$0 explore --range 1.2.4~3.2.1',
'Generate CHANGELOG summary from version 1.2.4 (exclusive) to version 3.2.1',
'Generate CHANGELOG summary from version 1.2.4 (exclusive) to version 3.2.1'
)
.example(
'$0 explore --range 1.2.4',
'Generate CHANGELOG summary from version 1.2.4 (exclusive) to the latest',
'Generate CHANGELOG summary from version 1.2.4 (exclusive) to the latest'
)
.string('range')
.alias('range', 'r')
.describe('range', 'Range of versions in a format like X.Y.Z ~ A.B.C')
.demandOption('range', 'Should provide a range!')
.default('range', defaults.range)
.string('output')
.alias('output', 'o')
.default('output', 'console')
.default('output', defaults.output)
.describe('output', 'Output path')
.string('input')
.alias('input', 'i')
.default('input', path.resolve(process.cwd(), './CHANGELOG.md'))
.default('input', defaults.input)
.describe('input', 'Input CHANGELOG for explore diffs')
.check((args) => {
const { range, output } = args;
const { range, output } = args
if (!range) {
throw new Error('Should provide a range!');
throw new Error('Should provide a range!')
}

if (output !== 'console' && !fs.lstatSync(output).isDirectory()) {
throw new Error('You must provide a folder, not a file path!');
throw new Error('You must provide a folder as --output, not a file path!')
}
return true; // tell Yargs that the arguments passed the check

return true // tell Yargs that the arguments passed the check
})
.help();
};
.help()
}

module.exports = {
argvBuilder,
};
argvBuilder
}
Loading

0 comments on commit b7f9676

Please sign in to comment.