diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2ddca2b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Develop and contribute + +## Setup + +```sh +git clone git@github.com:frinyvonnick/gitmoji-changelog.git + +cd gitmoji-changelog && yarn +``` + +We are using lerna and yarn workspaces to split the library in modules: +- [gitmoji-changelog-cli](https://github.com/frinyvonnick/gitmoji-changelog/tree/master/packages/gitmoji-changelog-cli) - the full-featured command line interface +- [gitmoji-changelog-core](https://github.com/frinyvonnick/gitmoji-changelog/tree/master/packages/gitmoji-changelog-core) - the core lib generating changelog +- [gitmoji-changelog-markdown](https://github.com/frinyvonnick/gitmoji-changelog/tree/master/packages/gitmoji-changelog-markdown) - the markdown changelog file writer + +## Usage locally + +```sh +node [path-to-gitmoji-changelog-folder]/packages/gitmoji-changelog-cli/src/index.js +``` + +## Run unit tests + +```sh +yarn test +# or +yarn test --watch +``` + +## Run e2e tests + +```sh +yarn test:e2e +``` + +## Run linter + +We are using [airbnb-base](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb-base) as linter: + +```sh +yarn lint +``` + + diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..6e4a212 --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,143 @@ +# Documentation + +## Usage + +Make sure you have [npx](https://www.npmjs.com/package/npx) installed (`npx` is shipped by default since npm `5.2.0`) + +Run the following command at the root of your project and answer questions. + +with npx: +```sh +npx gitmoji-changelog +``` + +with npm: +```sh +npm install -g gitmoji-changelog + +cd my-project +gitmoji-changelog +``` + +### Available commands + +```sh +gitmoji-changelog [release] +gitmoji-changelog init +gitmoji-changelog update [release] +``` + +The first command listed above is the idiomatic usage of `gitmoji-changelog` (read the `How it works` for more information). + +`release` argument is by default valued to `from-package`. It will retrieve the version from the selected `preset` (read `Presets` for more information). You can overwrite it with the tag you want to generate in the changelog. + +### Options + +| option | description | default value | +|-------------------------|-----------------------------------------|------------------------------------| +| --version | display version | | +| --format | changelog format (markdown, json) | markdown | +| --preset | define preset mode | node | +| --output | output file path | ./CHANGELOG.md or ./CHANGELOG.json | +| --group-similar-commits | [⚗️,- beta] try to group similar commits | false | +| --author | add the author in changelog lines | false | +| --interactive -i | select commits manually | false | +| --help | display help | | + +### Example + +**Here an example output:** [CHANGELOG.md](https://github.com/frinyvonnick/gitmoji-changelog/blob/master/CHANGELOG.md) + +## How it works + +### Behavior + +`CHANGELOG.md` doesn't exist: + +The CLI will generate all previous changelog based on semver tags of your repo. + +`CHANGELOG.md` exists: + +_All previous semvers tags remain unchanged_. The CLI will add each tag since the last semver tag found in the `CHANGELOG.md` file. + +**By default when you generate your changelog with `gitmoji-changelog`, the following mapping is used to group commits: [groupMapping.js](packages/gitmoji-changelog-core/src/groupMapping.js)** + +### Workflow + +Here the recommended workflow to generate your changelog file using `gitmoji-changelog`: + +**Important:** Before generating, be sure to have all tags locally (e.g. `git fetch origin`) + +1. Make changes and commit: `git commit -m ":sparkles: my awesome feature"` +2. Bump version (ex: `1.0.0`) in `package.json` using [semver](https://semver.org/) convention +3. Run `gitmoji-changelog`, then the file `CHANGELOG.md` is created or updated with all changes +4. You can freely edit the new release in the changelog file, it will not be overwrite with the next generation +5. Commit `package.json` and `CHANGELOG.md` file +6. Tag your release: `git tag -a v1.0.0 -m "v1.0.0"` (or create a Github release) +7. Push to the remote `git push` + +_This workflow is related to the `node` preset but can be adapted to your own technology._ + +## Presets + +`gitmoji-changelog` use presets to get project meta data useful for its smooth operation. Here is the list of available presets: + +- node (default preset) + +You didn't the preset you need in the list? Consider adding it. Presets are stored in a [presets](packages/gitmoji-changelog-cli/presets) folder in the `cli` package. + +### Add a preset + +A preset need to export a function. When called this function must return three mandatory information about the project in which the cli has been called. The name of the project, a short description of it and its current version. + +Let's dissect the `node` preset to see how it works. First of all the module must export a function. In case something went wrong return `null`. The cli will tell the user a problem occured. + +```js +module.exports = () => { + return null +} +``` + +There is a package called `read-pkg-up` to get the first `package.json` in the parent folder structure. It returns its content as a JavaScript object. If we can't find a `package.json` or it is empty we return `null`. + +```js +const readPkgUp = require('read-pkg-up') + +module.exports = async () => { + try { + const packageInfo = await readPkgUp() + + if (!packageInfo.pkg) { + throw Error('Empty package.json') + } + } catch (e) { + return null + } +} +``` + +If everything went fine we return the three mandatory information (name, description, version). + +```js +const readPkgUp = require('read-pkg-up') + +module.exports = async () => { + try { + const packageInfo = await readPkgUp() + + if (!packageInfo.pkg) { + throw Error('Empty package.json') + } + + return { + name: packageInfo.pkg.name, + description: packageInfo.pkg.description, + version: packageInfo.pkg.version, + } + } catch (e) { + return null + } +} +``` + +That's it. Feel free to open an issue to ask for a new preset or open a pull request to add one. diff --git a/README.md b/README.md index 4eaab0c..ac83909 100644 --- a/README.md +++ b/README.md @@ -18,14 +18,15 @@ > Generate changelog for repositories using [gitmoji](https://gitmoji.carloscuesta.me/) commits convention. -### 🏠 [Homepage](https://github.com/frinyvonnick/gitmoji-changelog#readme) + +![gitmoji-changelog usage example](https://raw.githubusercontent.com/frinyvonnick/gitmoji-changelog/master/misc/example.gif) ## [2.0](https://github.com/frinyvonnick/gitmoji-changelog/milestone/2) is in alpha :tada: gitmoji-changelog 2.0 in a nutshell: -- ✨ Add interactive option to manually select commits ([#81](https://github.com/frinyvonnick/gitmoji-changelog/issues/81)) [[d13ca2e](https://github.com/frinyvonnick/gitmoji-changelog/commit/d13ca2e1c77c3cd9694cde926442c303adb47fa3)] -- 🐛 Use last version from changelog file instead of previous git tag ([#82](https://github.com/frinyvonnick/gitmoji-changelog/issues/82)) [[d3c49d0](https://github.com/frinyvonnick/gitmoji-changelog/commit/d3c49d061cfbe2c271f9aa3739fae750dbf6327c)] -- 🐛 Fix dates sorting in commits ([#75](https://github.com/frinyvonnick/gitmoji-changelog/issues/75)) [[748e673](https://github.com/frinyvonnick/gitmoji-changelog/commit/748e6732a18f8bc5c529db12a558c0ffb458c8a1)] +- ✨ Add interactive option to manually select commits +- 💥 Remove package.json reading logic from core package +- ✨ Add a preset system to enable using `gitmoji-changelog` on all kind of projects Test it: @@ -33,22 +34,18 @@ Test it: npm install -g gitmoji-changelog@alpha ``` -## Supported tags and respective Dockerfile links - -* [yvonnick/gitmoji-changelog:latest](https://github.com/frinyvonnick/gitmoji-changelog/blob/master/Dockerfile) - - -## 🚀 Usage (with npx) +## 🚀 Usage Make sure you have [npx](https://www.npmjs.com/package/npx) installed (`npx` is shipped by default since npm `5.2.0`) -Run the following command at the root of your project and answer questions: +Run the following command at the root of your project and answer questions. + +with npx: ```sh npx gitmoji-changelog ``` -## 🚀 Usage (with npm) - +with npm: ```sh npm install -g gitmoji-changelog @@ -56,68 +53,7 @@ cd my-project gitmoji-changelog ``` -![gitmoji-changelog usage example](https://raw.githubusercontent.com/frinyvonnick/gitmoji-changelog/master/misc/example.gif) - -If `CHANGELOG.md` file doesn't exist, it will generate all previous changelog based on semver tags of your repo. - -If `CHANGELOG.md` file already exists, _this will not overwrite any previous changelog_, it will generate a changelog based on commits since the last semver tag that match. - -All available commands and parameters can be listed using: `gitmoji-changelog --help` - -**Here an example output:** [CHANGELOG.md](https://github.com/frinyvonnick/gitmoji-changelog/blob/master/CHANGELOG.md) - -_By default when you generate your changelog with `gitmoji-changelog`, the following mapping is used to group commits: [groupMapping.js](packages/gitmoji-changelog-core/src/groupMapping.js)_ - -## Workflow - -Here the recommended workflow to generate your changelog file using `gitmoji-changelog`: - -**Important:** Before generating, be sure to have all tags locally (e.g. `git fetch origin`) - -1. Make changes and commit: `git commit -m ":sparkles: my awesome feature"` -2. Bump version (ex: `1.0.0`) in `package.json` using [semver](https://semver.org/) convention -3. Run `gitmoji-changelog`, then the file `CHANGELOG.md` is created or updated with all changes -4. You can freely edit the new release in the changelog file, it will not be overwrite with the next generation -5. Commit `package.json` and `CHANGELOG.md` file -6. Tag your release: `git tag -a v1.0.0 -m "v1.0.0"` (or create a Github release) -7. Push to the remote `git push` - -## Develop and contribute - -### Setup - -```sh -git clone git@github.com:frinyvonnick/gitmoji-changelog.git - -cd gitmoji-changelog && yarn -``` - -We are using lerna and yarn workspaces to split the library in modules: -- [gitmoji-changelog-cli](https://github.com/frinyvonnick/gitmoji-changelog/tree/master/packages/gitmoji-changelog-cli) - the full-featured command line interface -- [gitmoji-changelog-core](https://github.com/frinyvonnick/gitmoji-changelog/tree/master/packages/gitmoji-changelog-core) - the core lib generating changelog -- [gitmoji-changelog-markdown](https://github.com/frinyvonnick/gitmoji-changelog/tree/master/packages/gitmoji-changelog-markdown) - the markdown changelog file writer - -### Usage locally - -```sh -node [path-to-gitmoji-changelog-folder]/packages/gitmoji-changelog-cli/src/index.js -``` - -### Run tests - -```sh -yarn test -# or -yarn test --watch -``` - -### Run linter - -We are using [airbnb-base](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb-base) as linter: - -```sh -yarn lint -``` +Read more in our [documentation](DOCUMENTATION.md). ### Using Docker image @@ -136,16 +72,21 @@ docker image build -t yvonnick/gitmoji-changelog:dev . docker container run -it -v $(pwd):/app --rm yvonnick/gitmoji-changelog:dev ``` +#### Supported tags and respective Dockerfile links + +* [yvonnick/gitmoji-changelog:latest](https://github.com/frinyvonnick/gitmoji-changelog/blob/master/Dockerfile) + + ## Author -👤 **Yvonnick FRIN (https://github.com/frinyvonnick)** +👤 **Yvonnick FRIN (https://yvonnickfrin.dev)** * Twitter: [@YvonnickFrin](https://twitter.com/YvonnickFrin) * Github: [@frinyvonnick](https://github.com/frinyvonnick) ## 🤝 Contributing -Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/frinyvonnick/gitmoji-changelog/issues). +Contributions, issues and feature requests are welcome!
Feel free to check [issues page](https://github.com/frinyvonnick/gitmoji-changelog/issues). You can also take a look at our [contributing guide](CONTRIBUTING.md). ## Show your support diff --git a/packages/gitmoji-changelog-cli/src/presets/node.js b/packages/gitmoji-changelog-cli/src/presets/node.js index 57f3498..de1a1a0 100644 --- a/packages/gitmoji-changelog-cli/src/presets/node.js +++ b/packages/gitmoji-changelog-cli/src/presets/node.js @@ -4,7 +4,7 @@ module.exports = async () => { try { const packageInfo = await readPkgUp() - if (!packageInfo.pkg) return null + if (!packageInfo.pkg) throw Error('Empty package.json') return { name: packageInfo.pkg.name,