📝 Improve documentation (#129)

frinyvonnick · Oct 31, 2019 · a2c994e · a2c994e
1 parent 24cead9
commit a2c994e
Show file tree

Hide file tree

Showing 4 changed files with 206 additions and 78 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Develop and contribute
+
+## Setup
+
+```sh
+git clone [email protected]: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
@@ -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
@@ -18,106 +18,42 @@
 
 > 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:
 
 ```shell
 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
 
 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 [email protected]: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!<br />Feel free to check [issues page](https://github.com/frinyvonnick/gitmoji-changelog/issues).
+Contributions, issues and feature requests are welcome!<br />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
@@ -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,