From ce3d1bc7151244064ff3b546046884e3cdc3eb02 Mon Sep 17 00:00:00 2001 From: Pierre Vanduynslager Date: Thu, 22 Aug 2019 12:09:15 -0400 Subject: [PATCH] revert: docs: corrections and further clarifications This reverts commit 7cb5446bb597b2a457ae4390a0658da5779ffb70. --- README.md | 14 +++++++------- SUMMARY.md | 12 ++++++------ docs/01-usage/configuration.md | 2 +- docs/01-usage/installation.md | 9 ++++++++- docs/01-usage/plugins.md | 4 ++-- docs/01-usage/shareable-configurations.md | 6 +++--- ...nes-recipes.md => ci-configurations-recipes.md} | 2 +- docs/03-recipes/git-hosted-services.md | 12 +++++++++++- 8 files changed, 39 insertions(+), 22 deletions(-) rename docs/03-recipes/{ci-pipelines-recipes.md => ci-configurations-recipes.md} (81%) diff --git a/README.md b/README.md index 5d294c7f..aeccdf91 100644 --- a/README.md +++ b/README.md @@ -93,22 +93,22 @@ After running the tests, the command `semantic-release` will execute the followi ## Documentation - Usage - - [Getting started](docs/01-usage/getting-started.md) + - [Getting started](docs/01-usage/01-getting-started.md) - [Installation](docs/01-usage/installation.md#installation) - [CI Configuration](docs/01-usage/ci-configuration.md#ci-configuration) - [Configuration](docs/01-usage/configuration.md#configuration) - [Plugins](docs/01-usage/plugins.md) - [Shareable configurations](docs/01-usage/shareable-configurations.md) - Extending - - [Available plugins](docs/02-extending/plugins-list.md) - - [Available shareable configuration](docs/02-extending/shareable-configurations-list.md) + - [Plugins](docs/02-extending/plugins-list.md) + - [Shareable configuration](docs/02-extending/shareable-configurations-list.md) - Recipes - [CI pipelines recipes](docs/03-recipes/ci-pipelines-recipes.md) - - [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md) - - [Travis CI](docs/03-recipes/travis.md) - - [GitLab CI](docs/03-recipes/gitlab-ci.md) + - [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md) + - [Travis CI](docs/03-recipes/travis.md) + - [GitLab CI](docs/03-recipes/gitlab-ci.md) - [Git hosted services](docs/03-recipes/git-hosted-services.md) - - [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md) + - [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md) - [Package managers and languages](docs/03-recipes/package-managers-and-languages.md) - Developer guide - [JavaScript API](docs/04-developer-guide/js-api.md) diff --git a/SUMMARY.md b/SUMMARY.md index e088aa11..74e4089e 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -9,16 +9,16 @@ - [Shareable configurations](docs/01-usage/shareable-configurations.md) ## Extensions -- [Available plugins](docs/02-extending/plugins-list.md) -- [Available shareable configuration](docs/02-extending/shareable-configurations-list.md) +- [Plugins](docs/02-extending/plugins-list.md) +- [Shareable configuration](docs/02-extending/shareable-configurations-list.md) ## Recipes - [CI pipelines recipes](docs/03-recipes/ci-pipelines-recipes.md) - - [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md) - - [Travis CI](docs/03-recipes/travis.md) - - [GitLab CI](docs/03-recipes/gitlab-ci.md) + - [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md) + - [Travis CI](docs/03-recipes/travis.md) + - [GitLab CI](docs/03-recipes/gitlab-ci.md) - [Git hosted services](docs/03-recipes/git-hosted-services.md) - - [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md) + - [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md) - [Package managers and languages](docs/03-recipes/package-managers-and-languages.md) ## Developer guide diff --git a/docs/01-usage/configuration.md b/docs/01-usage/configuration.md index 2cd5d882..23c380d0 100644 --- a/docs/01-usage/configuration.md +++ b/docs/01-usage/configuration.md @@ -154,7 +154,7 @@ Example (`.releaserc` file content): "@semantic-release/release-notes-generator", "@semantic-release-docker", ["@semantic-release/exec", { - "verifyConditionsCmd": "./verify.sh" + "verifyConditionsCmd": "./verify.sh" # plugin configuration }], "@semantic-release/git", "@semantic-release/gitlab", diff --git a/docs/01-usage/installation.md b/docs/01-usage/installation.md index 0cf89de2..64c27260 100644 --- a/docs/01-usage/installation.md +++ b/docs/01-usage/installation.md @@ -18,5 +18,12 @@ $ npx semantic-release ## Global installation -> **Note:** Global installation is no longer recommended. Please use local installation and `npx` instead. +For other type of projects we recommend installing **semantic-release** directly in the CI environment, also with [npx](https://www.npmjs.com/package/npx): +```bash +$ npx semantic-release +``` + +> **Note:** For a global installation, it's recommended to specify the major **semantic-release** version to install (for example with with `npx semantic-release@15`, or `npm install -g semantic-release@15`). This way your build will not automatically use the next major **semantic-release** release that could possibly break your build. You will have to upgrade manually when a new major version is released. + +> **Note:** `npx` is a tool bundled with `npm@>=5.2.0`. It is used to conveniently install the semantic-release binary and to execute it. See [What is npx](../05-support/FAQ.md#what-is-npx) for more details. diff --git a/docs/01-usage/plugins.md b/docs/01-usage/plugins.md index 69a64299..8f329e46 100644 --- a/docs/01-usage/plugins.md +++ b/docs/01-usage/plugins.md @@ -75,11 +75,11 @@ Global plugin options can defined at the root of the **semantic-release** config "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", ["@semantic-release/github", { - "assets": ["dist/**"] + "assets": ["dist/**"] # plugin configuration }], "@semantic-release/git" ], - "preset": "angular" + "preset": "angular" # option passed to all plugins } ``` diff --git a/docs/01-usage/shareable-configurations.md b/docs/01-usage/shareable-configurations.md index 7058267d..3e1a3ccf 100644 --- a/docs/01-usage/shareable-configurations.md +++ b/docs/01-usage/shareable-configurations.md @@ -1,7 +1,7 @@ # Shareable configurations -A shareable configuration is an npm package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects. +A shareable configuration is an [npm](https://www.npmjs.com/) package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects. -Shareable configurations to be use can be declared with the [`extends` option](configuration.md#extends). +The shareable configurations to use can be set with the [extends](configuration.md#extends) option. -See [shareable configurations list](../02-extending/shareable-configurations-list.md) for examples. +See [shareable configurations list](../02-extending/shareable-configurations-list.md). diff --git a/docs/03-recipes/ci-pipelines-recipes.md b/docs/03-recipes/ci-configurations-recipes.md similarity index 81% rename from docs/03-recipes/ci-pipelines-recipes.md rename to docs/03-recipes/ci-configurations-recipes.md index ed6f92d7..5126288f 100644 --- a/docs/03-recipes/ci-pipelines-recipes.md +++ b/docs/03-recipes/ci-configurations-recipes.md @@ -1,4 +1,4 @@ -# CI pipelines recipes +# CI configurations - [CircleCI 2.0 workflows](circleci-workflows.md) - [Travis CI](travis.md) - [GitLab CI](gitlab-ci.md) diff --git a/docs/03-recipes/git-hosted-services.md b/docs/03-recipes/git-hosted-services.md index 0df19570..fd2ad886 100644 --- a/docs/03-recipes/git-hosted-services.md +++ b/docs/03-recipes/git-hosted-services.md @@ -1,2 +1,12 @@ -# Git hosted services +# Recipes + +## CI configurations +- [CircleCI 2.0 workflows](circleci-workflows.md) +- [Travis CI](travis.md) +- [GitLab CI](gitlab-ci.md) + +## Git hosted services - [Git authentication with SSH keys](git-auth-ssh-keys.md) + +## Package managers and languages (to be completed) +