docs: harmonize docs with other plugins

semantic-release · Oct 8, 2018 · 1b291d8 · 1b291d8
1 parent a1266a1
commit 1b291d8
Show file tree

Hide file tree

Showing 2 changed files with 39 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # @semantic-release/changelog
 
-Set of [semantic-release](https://github.com/semantic-release/semantic-release) plugins for creating or updating a changelog file.
+[**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to create or update a changelog file.
 
 [![Travis](https://img.shields.io/travis/semantic-release/changelog.svg)](https://travis-ci.org/semantic-release/changelog)
 [![Codecov](https://img.shields.io/codecov/c/github/semantic-release/changelog.svg)](https://codecov.io/gh/semantic-release/changelog)
@@ -9,54 +9,57 @@ Set of [semantic-release](https://github.com/semantic-release/semantic-release)
 [![npm latest version](https://img.shields.io/npm/v/@semantic-release/changelog/latest.svg)](https://www.npmjs.com/package/@semantic-release/changelog)
 [![npm next version](https://img.shields.io/npm/v/@semantic-release/changelog/next.svg)](https://www.npmjs.com/package/@semantic-release/changelog)
 
-## verifyConditions
+| Step               | Description                                                                                                                                                                                           |
+|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `verifyConditions` | Verify the `changelogFile` and `changelogTitle` options configuration.                                                                                                                                |
+| `prepare`          | Create or update a changelog file in the local project directory with the changelog content created in the [generate notes step](https://github.com/semantic-release/semantic-release#release-steps). |
 
-Verify the `changelogFile` option configuration.
+## Install
 
-## prepare
-
-Create or update the changelog file in the local project repository.
-
-## Configuration
-
-### Options
-
-| Options          | Description                 | Default        |
-|------------------|-----------------------------|----------------|
-| `changelogFile`  | File path of the changelog. | `CHANGELOG.md` |
-| `changelogTitle` | Title in the changelog.     | None           |
-
-**Note**: If you use a [shareable configuration](https://github.com/semantic-release/semantic-release/blob/caribou/docs/usage/shareable-configurations.md#shareable-configurations) that defines one of these options you can set it to `false` in your [**semantic-release** configuration](https://github.com/semantic-release/semantic-release/blob/caribou/docs/usage/configuration.md#configuration) in order to use the default value.
+```bash
+$ npm install @semantic-release/changelog -D
+```
 
-### Usage
+## Usage
 
-Options can be set within the plugin definition in the `semantic-release` configuration file:
+The plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/caribou/docs/usage/configuration.md#configuration):
 
 ```json
 {
-  "release": {
-    "prepare": [
-      {
-        "path": "@semantic-release/changelog",
-        "changelogFile": "docs/changelog.md",
-      },
-      "@semantic-release/git"
-    ]
-  }
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    ["@semantic-release/changelog", {
+      "changelogFile": "docs/CHANGELOG.md",
+    }],
+    "@semantic-release/git",
+  ]
 }
 ```
 
-**It's recommended to use this plugin with the [git](https://github.com/semantic-release/git) plugin, so the changelog file will be committed to the Git repository and available on subsequent builds in order to be updated.**
+With this example, for each release, a `docs/CHANGELOG.md` will be created or updated.
+
+## Configuration
+
+### Options
+
+| Options          | Description                                           | Default        |
+|------------------|-------------------------------------------------------|----------------|
+| `changelogFile`  | File path of the changelog.                           | `CHANGELOG.md` |
+| `changelogTitle` | Title of the changelog file (first line of the file). | -              |
 
-**When using with the [npm](https://github.com/semantic-release/npm) plugin and/or the [git](https://github.com/semantic-release/git) plugin the `changelog` plugin must be called first in order to create or update the changelog file, so it can be included in the npm package and committed to the Git repository.**
+### Examples
 
-To use with the [npm](https://github.com/semantic-release/npm) and [git](https://github.com/semantic-release/git) plugins:
+When used with the [@semantic-release/git](https://github.com/semantic-release/git) or [@semantic-release/npm](https://github.com/semantic-release/npm) plugins the `@semantic-release/changelog` plugin must be called first in order to update the changelog file so the [@semantic-release/git](https://github.com/semantic-release/git) and [@semantic-release/npm](https://github.com/semantic-release/npm) plugins can include it in the release.
 
 ```json
 {
-  "release": {
-    "verifyConditions": ["@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/git"],
-    "prepare": ["@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/git"]
-  }
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/git"
+  ],
 }
 ```
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@semantic-release/changelog",
-  "description": "Set of semantic-release plugins for creating or updating a changelog file",
+  "description": "semantic-release plugin to create or update a changelog file",
   "version": "0.0.0-development",
   "author": "Pierre Vanduynslager (https://github.com/pvdlg)",
   "bugs": {