Skip to content
Permalink
Browse files

docs: made doc file org clearer and augmented content

This is a first step to improving the doc: - renamed directories; - augmented a fair bit of content.
To be continued
  • Loading branch information...
esciara authored and gr2m committed Jul 31, 2019
1 parent 2d2bb38 commit 5a5eaec3da5e3be4a505f6c5e7fa9eb81d202cea
Showing with 350 additions and 252 deletions.
  1. +3 −3 CONTRIBUTING.md
  2. +38 −38 README.md
  3. +24 −24 SUMMARY.md
  4. 0 docs/{usage → 01-usage}/README.md
  5. +30 −10 docs/{usage → 01-usage}/ci-configuration.md
  6. +131 −56 docs/{usage → 01-usage}/configuration.md
  7. +30 −0 docs/01-usage/getting-started.md
  8. +29 −0 docs/01-usage/installation.md
  9. +21 −26 docs/{usage → 01-usage}/plugins.md
  10. +1 −1 docs/{usage → 01-usage}/shareable-configurations.md
  11. 0 docs/{extending → 02-extending}/README.md
  12. 0 docs/{extending → 02-extending}/plugins-list.md
  13. 0 docs/{extending → 02-extending}/shareable-configurations-list.md
  14. 0 docs/{recipes → 03-recipes}/README.md
  15. 0 docs/{recipes/ci-configurations.md → 03-recipes/ci-configurations-recipes.md}
  16. +4 −4 docs/{recipes → 03-recipes}/circleci-workflows.md
  17. +1 −1 docs/{recipes → 03-recipes}/git-auth-ssh-keys.md
  18. 0 docs/{recipes → 03-recipes}/git-hosted-services.md
  19. +4 −4 docs/{recipes → 03-recipes}/gitlab-ci.md
  20. 0 docs/{recipes → 03-recipes}/package-managers-and-languages.md
  21. +6 −6 docs/{recipes → 03-recipes}/travis.md
  22. 0 docs/{developer-guide → 04-developer-guide}/README.md
  23. +3 −3 docs/{developer-guide → 04-developer-guide}/js-api.md
  24. 0 docs/{developer-guide → 04-developer-guide}/plugin.md
  25. 0 docs/{developer-guide → 04-developer-guide}/shareable-configuration.md
  26. +19 −19 docs/{support → 05-support}/FAQ.md
  27. 0 docs/{support → 05-support}/README.md
  28. 0 docs/{support → 05-support}/node-support-policy.md
  29. +1 −1 docs/{support → 05-support}/node-version.md
  30. 0 docs/{support → 05-support}/resources.md
  31. 0 docs/{support → 05-support}/troubleshooting.md
  32. +5 −5 docs/README.md
  33. +0 −22 docs/usage/getting-started.md
  34. +0 −29 docs/usage/installation.md
@@ -21,7 +21,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/03-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+).

Please follow the [Documentation guidelines](#documentation).

@@ -37,7 +37,7 @@ Confirmed bugs and ready-to-implement features are marked with the [help wanted

## Using the issue tracker

The issue tracker is the channel for [bug reports](#bug-report), [features requests](#feature-request) and [submitting pull requests](#submitting-a-pull-request) only. Please use the [Support](docs/support/README.md) and [Get help](README.md#get-help) sections for support, troubleshooting and questions.
The issue tracker is the channel for [bug reports](#bug-report), [features requests](#feature-request) and [submitting pull requests](#submitting-a-pull-request) only. Please use the [Support](docs/05-support/README.md) and [Get help](README.md#get-help) sections for support, troubleshooting and questions.

Before opening an issue or a Pull Request, please use the [GitHub issue search](https://github.com/issues?utf8=%E2%9C%93&q=user%3Asemantic-release) to make sure the bug or feature request hasn't been already reported or fixed.

@@ -51,7 +51,7 @@ Feature requests are welcome, but take a moment to find out whether your idea fi

### New plugin request

[Plugins](docs/usage/plugins.md) are a great way to extend **semantic-release** capabilities, integrate with other systems and support new project type. Please provide as much detail and context as possible and fill the information requested in the [New plugin request template](https://github.com/semantic-release/semantic-release/issues/new?template=plugin-request.md).
[Plugins](docs/01-usage/plugins.md) are a great way to extend **semantic-release** capabilities, integrate with other systems and support new project type. Please provide as much detail and context as possible and fill the information requested in the [New plugin request template](https://github.com/semantic-release/semantic-release/issues/new?template=plugin-request.md).

## Submitting a Pull Request

@@ -39,18 +39,18 @@ This removes the immediate connection between human emotions and version numbers
- New features and fixes are immediately available to users
- Notify maintainers and users of new releases
- Use formalized commit message convention to document changes in the codebase
- Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations)
- Integrate with your [continuous integration workflow](docs/03-recipes/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)
- Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
- Support any [package managers and languages](docs/03-recipes/README.md#package-managers-and-languages) via [plugins](docs/01-usage/plugins.md)
- Simple and reusable configuration via [shareable configurations](docs/01-usage/shareable-configurations.md)

## How does it work?

### Commit message format

**semantic-release** uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, **semantic-release** automatically determines the next [semantic version](https://semver.org) number, generates a changelog and publishes the release.

By default **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). The commit message format can be changed with the [`preset` or `config` options](docs/usage/configuration.md#options) of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins.
By default **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). The commit message format can be changed with the [`preset` or `config` options](docs/01-usage/configuration.md#options) of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins.

Tools such as [commitizen](https://github.com/commitizen/cz-cli), [commitlint](https://github.com/conventional-changelog/commitlint) or [semantic-git-commit-cli](https://github.com/JPeer264/node-semantic-git-commit-cli) can be used to help contributors and enforce valid commit messages.

@@ -78,48 +78,48 @@ If you need more control over the timing of releases you have a couple of option

After running the tests, the command `semantic-release` will execute the following steps:

| Step | Description |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Verify Conditions | Verify all the conditions to proceed with the release. |
| Get last release | Obtain the commit corresponding to the last release by analyzing [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). |
| Analyze commits | Determine the type of release based on the commits added since the last release. |
| Verify release | Verify the release conformity. |
| Generate notes | Generate release notes for the commits added since the last release. |
| Create Git tag | Create a Git tag corresponding to the new release version. |
| Prepare | Prepare the release. |
| Publish | Publish the release. |
| Notify | Notify of new releases or errors. |
| Step | Step Hook | Description |
|-------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Verify Conditions | `verifyConditions` | Verify all the conditions to proceed with the release. |
| Get last release | N/A | Obtain the commit corresponding to the last release by analyzing [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). |
| Analyze commits | N/A | Determine the type of release based on the commits added since the last release. |
| Verify release | `verifyRelease` | Verify the release conformity. |
| Generate notes | `generateNotes` | Generate release notes for the commits added since the last release. |
| Create Git tag | N/A | Create a Git tag corresponding to the new release version. |
| Prepare | `prepare` | Prepare the release. |
| Publish | `publish` | Publish the release. |
| Notify | `success`, `failure` | Notify of new releases or errors. |

## Documentation

- Usage
- [Getting started](docs/usage/getting-started.md)
- [Installation](docs/usage/installation.md#installation)
- [CI Configuration](docs/usage/ci-configuration.md#ci-configuration)
- [Configuration](docs/usage/configuration.md#configuration)
- [Plugins](docs/usage/plugins.md)
- [Shareable configurations](docs/usage/shareable-configurations.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
- [Plugins](docs/extending/plugins-list.md)
- [Shareable configuration](docs/extending/shareable-configurations-list.md)
- [Plugins](docs/02-extending/plugins-list.md)
- [Shareable configuration](docs/02-extending/shareable-configurations-list.md)
- Recipes
- [CI configurations](docs/recipes/ci-configurations.md)
- [CircleCI 2.0 workflows](docs/recipes/circleci-workflows.md)
- [Travis CI](docs/recipes/travis.md)
- [GitLab CI](docs/recipes/gitlab-ci.md)
- [Git hosted services](docs/recipes/git-hosted-services.md)
- [Git authentication with SSH keys](docs/recipes/git-auth-ssh-keys.md)
- [Package managers and languages](docs/recipes/package-managers-and-languages.md)
- [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)
- [Git hosted services](docs/03-recipes/git-hosted-services.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/developer-guide/js-api.md)
- [Plugin development](docs/developer-guide/plugin.md)
- [Shareable configuration development](docs/developer-guide/shareable-configuration.md)
- [JavaScript API](docs/04-developer-guide/js-api.md)
- [Plugin development](docs/04-developer-guide/plugin.md)
- [Shareable configuration development](docs/04-developer-guide/shareable-configuration.md)
- Support
- [Resources](docs/support/resources.md)
- [Frequently Asked Questions](docs/support/FAQ.md)
- [Troubleshooting](docs/support/troubleshooting.md)
- [Node version requirement](docs/support/node-version.md)
- [Node Support Policy](docs/support/node-support-policy.md)
- [Resources](docs/05-support/resources.md)
- [Frequently Asked Questions](docs/05-support/FAQ.md)
- [Troubleshooting](docs/05-support/troubleshooting.md)
- [Node version requirement](docs/05-support/node-version.md)
- [Node Support Policy](docs/05-support/node-support-policy.md)

## Get help

@@ -1,34 +1,34 @@
# Summary

## Usage
- [Getting started](docs/usage/getting-started.md)
- [Installation](docs/usage/installation.md#installation)
- [CI Configuration](docs/usage/ci-configuration.md#ci-configuration)
- [Configuration](docs/usage/configuration.md#configuration)
- [Plugins](docs/usage/plugins.md)
- [Shareable configurations](docs/usage/shareable-configurations.md)
- [Getting started](docs/01-usage/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
- [Plugins](docs/extending/plugins-list.md)
- [Shareable configuration](docs/extending/shareable-configurations-list.md)
## Extensions
- [Plugins](docs/02-extending/plugins-list.md)
- [Shareable configuration](docs/02-extending/shareable-configurations-list.md)

## Recipes
- [CI configurations](docs/recipes/ci-configurations.md)
- [CircleCI 2.0 workflows](docs/recipes/circleci-workflows.md)
- [Travis CI](docs/recipes/travis.md)
- [GitLab CI](docs/recipes/gitlab-ci.md)
- [Git hosted services](docs/recipes/git-hosted-services.md)
- [Git authentication with SSH keys](docs/recipes/git-auth-ssh-keys.md)
- [Package managers and languages](docs/recipes/package-managers-and-languages.md)
- [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)
- [Git hosted services](docs/03-recipes/git-hosted-services.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/developer-guide/js-api.md)
- [Plugin development](docs/developer-guide/plugin.md)
- [Shareable configuration development](docs/developer-guide/shareable-configuration.md)
- [JavaScript API](docs/04-developer-guide/js-api.md)
- [Plugin development](docs/04-developer-guide/plugin.md)
- [Shareable configuration development](docs/04-developer-guide/shareable-configuration.md)

## Support
- [Resources](docs/support/resources.md)
- [Frequently Asked Questions](docs/support/FAQ.md)
- [Troubleshooting](docs/support/troubleshooting.md)
- [Node version requirement](docs/support/node-version.md)
- [Node Support Policy](docs/support/node-support-policy.md)
- [Resources](docs/05-support/resources.md)
- [Frequently Asked Questions](docs/05-support/FAQ.md)
- [Troubleshooting](docs/05-support/troubleshooting.md)
- [Node version requirement](docs/05-support/node-version.md)
- [Node Support Policy](docs/05-support/node-support-policy.md)
File renamed without changes.

0 comments on commit 5a5eaec

Please sign in to comment.
You can’t perform that action at this time.