From 8fda7fd423d24e7b425fbee83790f49dd0478e2d Mon Sep 17 00:00:00 2001 From: Matt Travi Date: Sun, 14 Nov 2021 12:35:20 -0600 Subject: [PATCH] docs(recipes): moved recipes to sub-directories to align with gitbook expectations (#2246) --- CONTRIBUTING.md | 2 +- README.md | 18 +++++++------- SUMMARY.md | 24 +++++++++---------- docs/README.md | 2 +- docs/recipes/README.md | 16 ------------- docs/recipes/ci-configurations/README.md | 6 +++++ .../circleci-workflows.md | 4 ++-- .../{ => ci-configurations}/github-actions.md | 4 ++-- .../{ => ci-configurations}/gitlab-ci.md | 10 ++++---- .../{ => ci-configurations}/jenkins-ci.md | 8 +++---- .../recipes/{ => ci-configurations}/travis.md | 12 +++++----- docs/recipes/git-hosted-services/README.md | 2 ++ .../git-auth-ssh-keys.md | 2 +- docs/recipes/release-workflow/README.md | 4 ++++ .../distribution-channels.md | 4 ++-- .../maintenance-releases.md | 6 ++--- .../{ => release-workflow}/pre-releases.md | 4 ++-- docs/support/FAQ.md | 10 ++++---- docs/support/node-version.md | 2 +- docs/usage/ci-configuration.md | 6 ++--- docs/usage/workflow-configuration.md | 8 +++---- 21 files changed, 75 insertions(+), 79 deletions(-) delete mode 100644 docs/recipes/README.md create mode 100644 docs/recipes/ci-configurations/README.md rename docs/recipes/{ => ci-configurations}/circleci-workflows.md (86%) rename docs/recipes/{ => ci-configurations}/github-actions.md (94%) rename docs/recipes/{ => ci-configurations}/gitlab-ci.md (76%) rename docs/recipes/{ => ci-configurations}/jenkins-ci.md (77%) rename docs/recipes/{ => ci-configurations}/travis.md (81%) create mode 100644 docs/recipes/git-hosted-services/README.md rename docs/recipes/{ => git-hosted-services}/git-auth-ssh-keys.md (93%) create mode 100644 docs/recipes/release-workflow/README.md rename docs/recipes/{ => release-workflow}/distribution-channels.md (93%) rename docs/recipes/{ => release-workflow}/maintenance-releases.md (94%) rename docs/recipes/{ => release-workflow}/pre-releases.md (96%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3c40c58..7074a649 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ Help us keep **semantic-release** open and inclusive. Please read and follow our ### Improve documentation -As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes/README.md), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+). +As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+). Please follow the [Documentation guidelines](#documentation). diff --git a/README.md b/README.md index 16d34c32..91dc427a 100644 --- a/README.md +++ b/README.md @@ -37,9 +37,9 @@ This removes the immediate connection between human emotions and version numbers - Notify maintainers and users of new releases - Use formalized commit message convention to document changes in the codebase - Publish on different distribution channels (such as [npm dist-tags](https://docs.npmjs.com/cli/dist-tag)) based on git merges -- Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations) +- Integrate with your [continuous integration workflow](docs/recipes/release-workflow/README.md#ci-configurations) - Avoid potential errors associated with manual releases -- Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md) +- Support any [package managers and languages](docs/recipes/release-workflow/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md) - Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md) ## How does it work? @@ -74,9 +74,9 @@ For each new commit added to one of the release branches (for example: `master`, **semantic-release** offers various ways to control the timing, the content and the audience of published releases. See example workflows in the following recipes: -- [Using distribution channels](docs/recipes/distribution-channels.md#publishing-on-distribution-channels) -- [Maintenance releases](docs/recipes/maintenance-releases.md#publishing-maintenance-releases) -- [Pre-releases](docs/recipes/pre-releases.md#publishing-pre-releases) +- [Using distribution channels](docs/recipes/release-workflow/distribution-channels.md#publishing-on-distribution-channels) +- [Maintenance releases](docs/recipes/release-workflow/maintenance-releases.md#publishing-maintenance-releases) +- [Pre-releases](docs/recipes/release-workflow/pre-releases.md#publishing-pre-releases) ### Release steps @@ -117,10 +117,10 @@ In order to use **semantic-release** you need: - [Plugins](docs/extending/plugins-list.md) - [Shareable configuration](docs/extending/shareable-configurations-list.md) - Recipes - - [CI configurations](docs/recipes/README.md) - - [Git hosted services](docs/recipes/README.md) - - [Release workflow](docs/recipes/README.md) - - [Package managers and languages](docs/recipes/README.md) + - [CI configurations](docs/recipes/release-workflow/README.md) + - [Git hosted services](docs/recipes/release-workflow/README.md) + - [Release workflow](docs/recipes/release-workflow/README.md) + - [Package managers and languages](docs/recipes/release-workflow/README.md) - Developer guide - [JavaScript API](docs/developer-guide/js-api.md) - [Plugins development](docs/developer-guide/plugin.md) diff --git a/SUMMARY.md b/SUMMARY.md index 1d9a6bf7..c0459164 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -14,18 +14,18 @@ - [Shareable configuration](docs/extending/shareable-configurations-list.md) ## Recipes -- [CI configurations](docs/recipes/README.md#ci-configurations) - - [CircleCI 2.0](docs/recipes/circleci-workflows.md) - - [Travis CI](docs/recipes/travis.md) - - [GitLab CI](docs/recipes/gitlab-ci.md) - - [GitHub Actions](docs/recipes/github-actions.md) - - [Jenkins CI](docs/recipes/jenkins-ci.md) -- [Git hosted services](docs/recipes/README.md#git-hosted-services) - - [Git authentication with SSH keys](docs/recipes/git-auth-ssh-keys.md) -- [Release Workflow](docs/recipes/README.md#release-workflow) - - [Publishing on distribution channels](docs/recipes/distribution-channels.md) - - [Publishing maintenance releases](docs/recipes/maintenance-releases.md) - - [Publishing pre-releases](docs/recipes/pre-releases.md) +- [CI configurations](docs/recipes/ci-configurations/README.md) + - [CircleCI 2.0](docs/recipes/ci-configurations/circleci-workflows.md) + - [Travis CI](docs/recipes/ci-configurations/travis.md) + - [GitLab CI](docs/recipes/ci-configurations/gitlab-ci.md) + - [GitHub Actions](docs/recipes/ci-configurations/github-actions.md) + - [Jenkins CI](docs/recipes/ci-configurations/jenkins-ci.md) +- [Git hosted services](docs/recipes/git-hosted-services/README.md) + - [Git authentication with SSH keys](docs/recipes/git-hosted-services/git-auth-ssh-keys.md) +- [Release Workflow](docs/recipes/release-workflow/README.md) + - [Publishing on distribution channels](docs/recipes/release-workflow/distribution-channels.md) + - [Publishing maintenance releases](docs/recipes/release-workflow/maintenance-releases.md) + - [Publishing pre-releases](docs/recipes/release-workflow/pre-releases.md) ## Developer guide - [JavaScript API](docs/developer-guide/js-api.md) diff --git a/docs/README.md b/docs/README.md index ce1e098c..748d0702 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,6 @@ - [Usage](usage/README.md) - **semantic-release** installation and configuration - [Extending](extending/README.md) - Extending **semantic-release** with plugins and shareable configurations -- [Recipes](recipes/README.md) - Community written recipes for common **semantic-release** use-cases +- [Recipes](recipes/release-workflow/README.md) - Community written recipes for common **semantic-release** use-cases - [Developer Guide](developer-guide/README.md) - The essentials of writing a **semantic-release** plugin or shareable configurations - [Support](support/README.md) - FAQ and troubleshooting diff --git a/docs/recipes/README.md b/docs/recipes/README.md deleted file mode 100644 index 78d1dd23..00000000 --- a/docs/recipes/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# Recipes - -## CI configurations -- [CircleCI 2.0 workflows](circleci-workflows.md) -- [Travis CI](travis.md) -- [GitLab CI](gitlab-ci.md) -- [GitHub Actions](github-actions.md) -- [Jenkins CI](jenkins-ci.md) - -## Git hosted services -- [Git authentication with SSH keys](git-auth-ssh-keys.md) - -## Release workflow -- [Publishing on distribution channels](distribution-channels.md) -- [Publishing maintenance releases](maintenance-releases.md) -- [Publishing pre-releases](pre-releases.md) diff --git a/docs/recipes/ci-configurations/README.md b/docs/recipes/ci-configurations/README.md new file mode 100644 index 00000000..6a260853 --- /dev/null +++ b/docs/recipes/ci-configurations/README.md @@ -0,0 +1,6 @@ +# CI configurations +- [CircleCI 2.0 workflows](circleci-workflows.md) +- [Travis CI](travis.md) +- [GitLab CI](gitlab-ci.md) +- [GitHub Actions](github-actions.md) +- [Jenkins CI](jenkins-ci.md) diff --git a/docs/recipes/circleci-workflows.md b/docs/recipes/ci-configurations/circleci-workflows.md similarity index 86% rename from docs/recipes/circleci-workflows.md rename to docs/recipes/ci-configurations/circleci-workflows.md index 548aaf1f..468e23b5 100644 --- a/docs/recipes/circleci-workflows.md +++ b/docs/recipes/ci-configurations/circleci-workflows.md @@ -2,9 +2,9 @@ ## Environment variables -The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app).. +The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app).. -Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started). +Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started). ## Multiple Node jobs configuration diff --git a/docs/recipes/github-actions.md b/docs/recipes/ci-configurations/github-actions.md similarity index 94% rename from docs/recipes/github-actions.md rename to docs/recipes/ci-configurations/github-actions.md index a5c8d0ab..e0a91f97 100644 --- a/docs/recipes/github-actions.md +++ b/docs/recipes/ci-configurations/github-actions.md @@ -2,7 +2,7 @@ ## Environment variables -The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets). +The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets). In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) is required to publish a package to the npm registry. GitHub Actions [automatically populate](https://help.github.com/en/articles/virtual-environments-for-github-actions#github_token-secret) a [`GITHUB_TOKEN`](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) environment variable which can be used in Workflows. @@ -10,7 +10,7 @@ In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and [GitHub Actions](https://github.com/features/actions) support [Workflows](https://help.github.com/en/articles/configuring-workflows), allowing to run tests on multiple Node versions and publish a release only when all test pass. -**Note**: The publish pipeline must run on a [Node version that meets our version requirement](../support/node-version.md). +**Note**: The publish pipeline must run on a [Node version that meets our version requirement](../../support/node-version.md). ### `.github/workflows/release.yml` configuration for Node projects diff --git a/docs/recipes/gitlab-ci.md b/docs/recipes/ci-configurations/gitlab-ci.md similarity index 76% rename from docs/recipes/gitlab-ci.md rename to docs/recipes/ci-configurations/gitlab-ci.md index 84c53ed3..1276a855 100644 --- a/docs/recipes/gitlab-ci.md +++ b/docs/recipes/ci-configurations/gitlab-ci.md @@ -2,7 +2,7 @@ ## Environment variables -The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables). +The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables). **Note**: Make sure to configure your release branch as [protected](https://docs.gitlab.com/ce/user/project/protected_branches.html) in order for the CI/CD build to access the protected variables. @@ -10,13 +10,13 @@ The [Authentication](../usage/ci-configuration.md#authentication) environment va GitLab CI supports [Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html) allowing to test on multiple Node versions and publishing a release only when all test pass. -**Note**: The publish pipeline must run a [Node version that meets our version requirement](../support/node-version.md). +**Note**: The publish pipeline must run a [Node version that meets our version requirement](../../support/node-version.md). ### `.gitlab-ci.yml` configuration for Node projects This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options. -**Note**: The`semantic-release` execution command varies depending on whether you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) **semantic-release** installation. +**Note**: The`semantic-release` execution command varies depending on whether you are using a [local](../../usage/installation.md#local-installation) or [global](../../usage/installation.md#global-installation) **semantic-release** installation. ```yaml # The release pipeline will run only if all jobs in the test pipeline are successful @@ -50,7 +50,7 @@ publish: This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options. -**Note**: The`semantic-release` execution command varies depending if you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) **semantic-release** installation. +**Note**: The`semantic-release` execution command varies depending if you are using a [local](../../usage/installation.md#local-installation) or [global](../../usage/installation.md#global-installation) **semantic-release** installation. ```yaml @@ -83,7 +83,7 @@ release: ### `package.json` configuration -A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation. +A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation. ```json { diff --git a/docs/recipes/jenkins-ci.md b/docs/recipes/ci-configurations/jenkins-ci.md similarity index 77% rename from docs/recipes/jenkins-ci.md rename to docs/recipes/ci-configurations/jenkins-ci.md index d5a36dac..69b6d880 100644 --- a/docs/recipes/jenkins-ci.md +++ b/docs/recipes/ci-configurations/jenkins-ci.md @@ -2,15 +2,15 @@ ## Environment variables -The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/).. +The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/).. -Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started). +Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started). ## Node.js project configuration ### `Jenkinsfile (Declarative Pipeline)` configuration for a Node.js job -**Note**: The publish pipeline must run a Node version that [meets our requirement](../support/node-version.md). +**Note**: The publish pipeline must run a Node version that [meets our requirement](../../support/node-version.md). This example is a minimal configuration for **semantic-release** with a build running a version of Node labelled as "node LTS". Since versions of Node are manually downloaded and labelled, we recommend keeping the version used for the release steps up-to-date with the latest LTS version. @@ -50,7 +50,7 @@ pipeline { ### `package.json` configuration for a Node job -A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation. +A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation. ```json { diff --git a/docs/recipes/travis.md b/docs/recipes/ci-configurations/travis.md similarity index 81% rename from docs/recipes/travis.md rename to docs/recipes/ci-configurations/travis.md index d789a0d1..1a9a0520 100644 --- a/docs/recipes/travis.md +++ b/docs/recipes/ci-configurations/travis.md @@ -2,9 +2,9 @@ ## Environment variables -The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env). +The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env). -Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started). +Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../../usage/getting-started.md#getting-started). ## Node.js projects configuration @@ -12,7 +12,7 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with This example is a minimal configuration for **semantic-release** with a build running Node 14 and 16. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options. -This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded). +This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded). It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification. @@ -43,7 +43,7 @@ jobs: ### `package.json` configuration for multiple Node jobs -A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation. +A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation. ```json { @@ -57,13 +57,13 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins For projects that require to be tested with one or multiple version of a Non-JavaScript [language](https://docs.travis-ci.com/user/languages), optionally on multiple [Operating Systems](https://docs.travis-ci.com/user/multi-os). -This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration. +This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration. ### `.travis.yml` configuration for non-JavaScript projects This example is a minimal configuration for **semantic-release** with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go). See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options. -This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded). +This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded). It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification. diff --git a/docs/recipes/git-hosted-services/README.md b/docs/recipes/git-hosted-services/README.md new file mode 100644 index 00000000..0df19570 --- /dev/null +++ b/docs/recipes/git-hosted-services/README.md @@ -0,0 +1,2 @@ +# Git hosted services +- [Git authentication with SSH keys](git-auth-ssh-keys.md) diff --git a/docs/recipes/git-auth-ssh-keys.md b/docs/recipes/git-hosted-services/git-auth-ssh-keys.md similarity index 93% rename from docs/recipes/git-auth-ssh-keys.md rename to docs/recipes/git-hosted-services/git-auth-ssh-keys.md index f346d802..69703cf9 100644 --- a/docs/recipes/git-auth-ssh-keys.md +++ b/docs/recipes/git-hosted-services/git-auth-ssh-keys.md @@ -1,6 +1,6 @@ # Git authentication with SSH keys -When using [environment variables](../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../usage/configuration.md#configuration) (the format will be automatically converted as needed). +When using [environment variables](../../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../../usage/configuration.md#configuration) (the format will be automatically converted as needed). Alternatively the Git repository can be accessed via [SSH](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) by creating SSH keys, adding the public one to your Git hosted account and making the private one available on the CI environment. diff --git a/docs/recipes/release-workflow/README.md b/docs/recipes/release-workflow/README.md new file mode 100644 index 00000000..36f94a49 --- /dev/null +++ b/docs/recipes/release-workflow/README.md @@ -0,0 +1,4 @@ +# Release workflow +- [Publishing on distribution channels](distribution-channels.md) +- [Publishing maintenance releases](maintenance-releases.md) +- [Publishing pre-releases](pre-releases.md) diff --git a/docs/recipes/distribution-channels.md b/docs/recipes/release-workflow/distribution-channels.md similarity index 93% rename from docs/recipes/distribution-channels.md rename to docs/recipes/release-workflow/distribution-channels.md index 49052d7a..557c2a47 100644 --- a/docs/recipes/distribution-channels.md +++ b/docs/recipes/release-workflow/distribution-channels.md @@ -3,8 +3,8 @@ This recipe will walk you through a simple example that uses distribution channels to make releases available only to a subset of users, in order to collect feedbacks before distributing the release to all users. This example uses the **semantic-release** default configuration: -- [branches](../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]` -- [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']` +- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]` +- [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']` ## Initial release diff --git a/docs/recipes/maintenance-releases.md b/docs/recipes/release-workflow/maintenance-releases.md similarity index 94% rename from docs/recipes/maintenance-releases.md rename to docs/recipes/release-workflow/maintenance-releases.md index 599ebb91..b0c57153 100644 --- a/docs/recipes/maintenance-releases.md +++ b/docs/recipes/release-workflow/maintenance-releases.md @@ -3,8 +3,8 @@ This recipe will walk you through a simple example that uses Git branches and distribution channels to publish fixes and features for old versions of a package. This example uses the **semantic-release** default configuration: -- [branches](../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]` -- [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']` +- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]` +- [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']` ## Initial release @@ -18,7 +18,7 @@ The Git history of the repository is: ## Releasing a breaking change -We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change. +We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change. We commit that change with the message `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required` to `master`. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`. diff --git a/docs/recipes/pre-releases.md b/docs/recipes/release-workflow/pre-releases.md similarity index 96% rename from docs/recipes/pre-releases.md rename to docs/recipes/release-workflow/pre-releases.md index e8edd447..0b984b7e 100644 --- a/docs/recipes/pre-releases.md +++ b/docs/recipes/release-workflow/pre-releases.md @@ -3,8 +3,8 @@ This recipe will walk you through a simple example that uses pre-releases to publish beta versions while working on a future major release and then make only one release on the default distribution. This example uses the **semantic-release** default configuration: -- [branches](../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]` -- [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']` +- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]` +- [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']` ## Initial release diff --git a/docs/support/FAQ.md b/docs/support/FAQ.md index 31242bba..2759b10b 100644 --- a/docs/support/FAQ.md +++ b/docs/support/FAQ.md @@ -47,7 +47,7 @@ To publish a non-Node package (without a `package.json`) you would need to: - Set **semantic-release** [options](../usage/configuration.md#options) via [CLI arguments or rc file](../usage/configuration.md#configuration) - Make sure your CI job executing the `semantic-release` command has access to a version of Node that [meets our version requirement](./node-version.md) to execute the `semantic-release` command -See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments. +See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments. In addition, you will need to configure the **semantic-release** [plugins](../usage/plugins.md#plugins) to disable the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin which is used by default and use a plugin for your project type. @@ -71,7 +71,7 @@ Here is a basic example to create [GitHub releases](https://help.github.com/arti **Note**: This is a theoretical example where the command `set-version` update the project version with the value passed as its first argument and `publish-package` publishes the package to a registry. -See the [package managers and languages recipes](../recipes/README.md#package-managers-and-languages) for more details on specific project types. +See the [package managers and languages recipes](../recipes/release-workflow/README.md#package-managers-and-languages) for more details on specific project types. ## Can I use semantic-release with any CI service? @@ -79,7 +79,7 @@ Yes, **semantic-release** can be used with any CI service, as long as it provide - A way to set [authentication](../usage/ci-configuration.md#authentication) via environment variables - A way to guarantee that the `semantic-release` command is [executed only after all the tests of all the jobs in the CI build pass](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded) -See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments. +See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments. ## Can I run semantic-release on my local machine rather than on a CI server? @@ -95,7 +95,7 @@ However this is not the recommended approach, as running unit and integration te Yes, with the [`@semantic-release/gitlab-config`](https://github.com/semantic-release/gitlab-config) shareable configuration. -See the [GitLab CI recipes](../recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration. +See the [GitLab CI recipes](../recipes/ci-configurations/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration. ## Can I use semantic-release with any Git hosted environment? @@ -194,7 +194,7 @@ If you need more control over the timing of releases, see [Triggering a release] This is not supported by **semantic-release** as it's not considered a good practice, mostly because [Semantic Versioning](https://semver.org) rules applies differently to major version zero. -If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend [publishing pre-releases](../recipes/pre-releases.md#publishing-pre-releases). +If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend [publishing pre-releases](../recipes/release-workflow/pre-releases.md#publishing-pre-releases). See [“Introduction to SemVer” - Irina Gebauer](https://blog.greenkeeper.io/introduction-to-semver-d272990c44f2) for more details on [Semantic Versioning](https://semver.org) and the recommendation to start at version `1.0.0`. diff --git a/docs/support/node-version.md b/docs/support/node-version.md index 43bb6df0..88b4117b 100644 --- a/docs/support/node-version.md +++ b/docs/support/node-version.md @@ -14,7 +14,7 @@ See our [Node Support Policy](node-support-policy.md) for our long-term promise The recommended approach is to run the `semantic-release` command from a CI job running on the latest available LTS version of node. This can either be a job used by your project to test on the latest Node LTS version or a dedicated job for the release steps. -See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/README.md#ci-configurations) for more details. +See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details. ## Alternative solutions diff --git a/docs/usage/ci-configuration.md b/docs/usage/ci-configuration.md index 90cdb06b..944eeb5f 100644 --- a/docs/usage/ci-configuration.md +++ b/docs/usage/ci-configuration.md @@ -13,7 +13,7 @@ Here is a few example of the CI services that can be used to achieve this: - [Wercker Workflows](http://devcenter.wercker.com/docs/workflows) - [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline). -See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details. +See [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details. ## Authentication @@ -29,7 +29,7 @@ See [CI configuration recipes](../recipes/README.md#ci-configurations) for more | `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clearification `user:token` has to be the value of this env. | | `GIT_CREDENTIALS` | [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) Git username and password in the format `:`. The username and password must each be individually URL encoded, not the `:` separating them. | -Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-auth-ssh-keys.md). +Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-hosted-services/git-auth-ssh-keys.md). ### Authentication for plugins @@ -44,6 +44,6 @@ See each plugin's documentation for the environment variables required. The authentication token/credentials have to be made available in the CI service via environment variables. -See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on how to configure environment variables in your CI service. +See [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on how to configure environment variables in your CI service. **Note**: The environment variables `GH_TOKEN`, `GITHUB_TOKEN`, `GL_TOKEN` and `GITLAB_TOKEN` can be used for both the Git authentication and the API authentication required by [@semantic-release/github](https://github.com/semantic-release/github) and [@semantic-release/gitlab](https://github.com/semantic-release/gitlab). diff --git a/docs/usage/workflow-configuration.md b/docs/usage/workflow-configuration.md index e7c9af93..c824e100 100644 --- a/docs/usage/workflow-configuration.md +++ b/docs/usage/workflow-configuration.md @@ -6,7 +6,7 @@ - Maintain multiple lines of releases in parallel - Work on large future releases outside the normal flow of one version increment per Git push -See [Release workflow recipes](../recipes/README.md#release-workflow) for detailed examples. +See [Release workflow recipes](../recipes/release-workflow/README.md#release-workflow) for detailed examples. The release workflow is configured via the [branches option](./configuration.md#branches) which accepts a single or an array of branch definitions. Each branch can be defined either as a string, a [glob](https://github.com/micromatch/micromatch#matching-features) or an object. For string and glob definitions each [property](#branches-properties) will be defaulted. @@ -108,7 +108,7 @@ A project must define a minimum of 1 release branch and can have a maximum of 3. **Note:** With **semantic-release** as with most package managers, a release version must be unique, independently of the distribution channel on which it is available. -See [publishing on distribution channels recipe](../recipes/distribution-channels.md) for a detailed example. +See [publishing on distribution channels recipe](../recipes/release-workflow/distribution-channels.md) for a detailed example. #### Pushing to a release branch @@ -142,7 +142,7 @@ Maintenance branches are always considered lower than [release branches](#releas **semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release or maintenance branch to another maintenance branch](#merging-into-a-maintenance-branch), however only versions within the branch `range` can be merged. If a merged version is outside the maintenance branch `range`, **semantic-release** will not add to the corresponding channel and will throw an `EINVALIDMAINTENANCEMERGE` error. -See [publishing maintenance releases recipe](../recipes/maintenance-releases.md) for a detailed example. +See [publishing maintenance releases recipe](../recipes/release-workflow/maintenance-releases.md) for a detailed example. #### Pushing to a maintenance branch @@ -171,7 +171,7 @@ A pre-release branch is characterized by the `prerelease` property that defines When merging commits associated with an existing release, **semantic-release** will treat them as [pushed commits](#pushing-to-a-pre-release-branch) and publish a new release if necessary, but it will never add those releases to the distribution channel corresponding to the pre-release branch. -See [publishing pre-releases recipe](../recipes/pre-releases.md) for a detailed example. +See [publishing pre-releases recipe](../recipes/release-workflow/pre-releases.md) for a detailed example. #### Pushing to a pre-release branch