From ed89361d7c55f6aef2c3e010ce592454ca93a837 Mon Sep 17 00:00:00 2001 From: Pierre Vanduynslager Date: Fri, 29 Dec 2017 04:54:07 -0500 Subject: [PATCH] docs: documentation improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Refactor and clarify the documentation in `README.md`** - Add Highlights - Add a Table of contents - Clarify the way semantic-release works - Clarify relationship with the CI environments - Describe local install for Node projects (with a `package.json`) and global install for non-JavaScript projects - Explain CI general configuration (environment variables and a run after all jobs are successful) - Clarify configuration (via config file or CLI arguments) - Clarify plugin roles and configuration - Add doc for shareable configuration - Add recipes - Add resources (Videos, articles, tutorials) - Add a Support section - Add a Team section **Add the following FAQs** - How can I use a npm build script that requires the `package.json`’s version ? - Can I use Semantic-release with Yarn? - Can I use Semantic-release to publish non-JavaScript packages? - Can I use Semantic-release with any CI service? - Can I use Semantic-release with any GitLab? - Can I use Semantic-release with any Git hosted environment? - Can I skip the release to the npm registry? - Can I use .npmrc options? - How can I set the access level of the published npm package? - Can I use Semantic-release to publish a package on Artifactory? - Can I set the initial release version of my package to 0.0.1? - Why does semantic-release require Node version >= 8? **Clarify Nove 8 requirement and solutions** - Add Node version requirement explanation and solutions - [X] Display a link to the documentation when running on Node < 8 version **Add recipes** - Travis - GitLab CI - Travis with build stages - To be done in #573 - CircleCI workflows - To be done in #573 --- README.md | 708 +++++++++++++----- bin/semantic-release.js | 18 +- docs/README.md | 7 + docs/developer-guide/README.md | 1 + docs/developer-guide/plugin.md | 1 + .../shareable-configuration.md | 1 + docs/node-version.md | 52 ++ docs/plugins.md | 37 + docs/recipes/README.md | 9 + docs/recipes/circleci-workflows.md | 1 + docs/recipes/gitlab-ci.md | 71 ++ docs/recipes/travis-build-stages.md | 1 + docs/recipes/travis.md | 151 ++++ docs/shareable-configurations.md | 7 + TROUBLESHOOTING.md => docs/troubleshooting.md | 0 media/semantic-release-cli.png | Bin 0 -> 119601 bytes package.json | 8 +- 17 files changed, 853 insertions(+), 220 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/developer-guide/README.md create mode 100644 docs/developer-guide/plugin.md create mode 100644 docs/developer-guide/shareable-configuration.md create mode 100644 docs/node-version.md create mode 100644 docs/plugins.md create mode 100644 docs/recipes/README.md create mode 100644 docs/recipes/circleci-workflows.md create mode 100644 docs/recipes/gitlab-ci.md create mode 100644 docs/recipes/travis-build-stages.md create mode 100644 docs/recipes/travis.md create mode 100644 docs/shareable-configurations.md rename TROUBLESHOOTING.md => docs/troubleshooting.md (100%) create mode 100644 media/semantic-release-cli.png diff --git a/README.md b/README.md index 0484c091..4b4b73c9 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,6 @@ # :package::rocket: semantic-release -**Fully automated package publishing** - -> **Trust us, this will change your workflow for the better.** - -> – [egghead.io](https://egghead.io/lessons/javascript-how-to-write-a-javascript-library-automating-releases-with-semantic-release) +Fully automated version management and package publishing. [![Gitter](https://badges.gitter.im/semantic-release/semantic-release.svg)](https://gitter.im/semantic-release/semantic-release?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Travis](https://img.shields.io/travis/semantic-release/semantic-release/caribou.svg)](https://travis-ci.org/semantic-release/semantic-release) @@ -15,123 +11,137 @@ [![npm](https://img.shields.io/npm/v/semantic-release/latest.svg)](https://www.npmjs.com/package/semantic-release) [![npm](https://img.shields.io/npm/v/semantic-release/next.svg)](https://www.npmjs.com/package/semantic-release) -Out of the box this is just about _commit-messages_, but you can do so much more. +semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package. This removes the immediate connection between human emotions and version numbers, strictly following the [Semantic Versioning](http://semver.org) specification. -* **Detect breaking changes** using the test suite of your last release: [cracks](https://github.com/semantic-release/cracks) -* Detect breaking changes using your dependents’ test suites: [Help out! Implement the **dont-break** plugin](https://github.com/semantic-release/semantic-release/issues/65) -* Detect breaking changes diffing your JSDoc interface: [Help out! Implement the **india** plugin](https://github.com/semantic-release/semantic-release/issues/66) -* Abort releases with **insufficient test coverage**: [Help out! Implement the **istanbul** plugin](https://github.com/semantic-release/semantic-release/issues/68) -* Abort releases with **vulnerable dependencies** in the tree: [Help out! Implement the **nsp** plugin](https://github.com/semantic-release/semantic-release/issues/67) -* Everything you can imagine: [Build Plugins!](https://github.com/semantic-release/semantic-release#plugins) +> Trust us, this will change your workflow for the better. – [egghead.io](https://egghead.io/lessons/javascript-how-to-write-a-javascript-library-automating-releases-with-semantic-release) -  | Commands | Comment ---- | --- | --- -| **manual/before** | 
npm version major
git push origin master --tags
npm publish
| You **manually decide** what the **next version** is. You have to remember what major, minor and patch means. You have to remember to push both commits and tags. You have to wait for the CI to pass. | -| **semantic-release/after** | 
git commit -m "fix: <message>"
git push
| You **describe the changes** you’ve made. A new version is automatically published with the correct version number. +## Highlights -This removes the immediate connection between human emotions and version numbers, so strictly following the [SemVer](http://semver.org/) spec is not a problem anymore – and that’s ultimately `semantic-release`’s goal. +- Fully automated release +- Enforce [Semantic Versioning](https://semver.org) specification +- New features and fixes are immediately available to users +- Use formalized commit message convention to document changes in the codebase +- Integrate with your [continuous integration workflow](docs/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](#plugins) +- Simple and reusable configuration via [shareable configurations](#shareable-configurations) - - - - - - - - - - - - - - - - - - - - - - -
- “How to Write a JavaScript Library - Automating Releases with semantic-release” – egghead.io -
- egghead.io session -
- A free egghead.io tutorial series on how to write an open source library featuring semantic-release. -
- “We fail to follow SemVer – and why it needn’t matter” - - “semantic-release Q&A with Kent C. Dodds” -
- JSConfBP Talk - - Hangout on Air with Kent C. Dodds -
- This talk gives you a complete introduction to the underlying concepts of this module. 38:30 - - A “Hangouts on Air” conversation with hands on questions and answers about how to use semantic-release. 53:52 -
+## Table of Contents + +- [How does it work?](#how-does-it-work) +- [Installation and Usage](#installation-and-usage) +- [Plugins](#plugins) +- [Shareable configurations](#shareable-configurations) +- [Recipes](#recipes) +- [Frequently Asked Questions](#frequently-asked-questions) +- [Resources](#resources) +- [Support](#support) +- [Badge](#badge) +- [Node Support Policy](#node-support-policy) +- [Team](#team) ## How does it work? -Instead of writing [meaningless commit messages](http://whatthecommit.com/), we can take our time to think about the changes in the codebase and write them down. Following formalized conventions it is then possible to generate a helpful changelog and to derive the next semantic version number from them. +### Commit message format -When `semantic-release` is set up it will do that after every successful continuous integration build of your master branch (or any other branch you specify) and publish the new version for you. This way no human is directly involved in the release process and your releases are guaranteed to be [unromantic and unsentimental](http://sentimentalversioning.org/). +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 publish the release. -If you fear the loss of control over timing and marketing implications of software releases you should know that `semantic-release` supports [release channels](https://github.com/npm/npm/issues/2718) using `npm`’s [dist-tags](https://docs.npmjs.com/cli/dist-tag). This way you can keep control over what your users end up using by default, you can decide when to promote an automatically released version to the stable channel, and you can choose which versions to write blogposts and tweets about. You can use the same mechanism to [support older versions of your software](https://gist.github.com/boennemann/54042374e49c7ade8910), for example with important security fixes. +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 that can changed with the [`preset` or `config` options](#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. -When pushing new commits with `git push` a CI build is triggered. After running the tests the command `semantic-release` will execute the following tasks in series: +Tools such as [commitizen](https://github.com/commitizen/cz-cli), [commitlint](https://github.com/marionebl/commitlint) or [semantic-git-commit-cli](https://github.com/JPeer264/node-semantic-git-commit-cli) can be used to help contributor and enforce valid commits message. -| Step | Description | -| ------------------ | ------------------------------------------------------------------------------------------- | -| Verify Conditions | Run the [verifyConditions](#verifyconditions) plugin | -| Get last release | Obtain last release with the [getLastRelease](#getlastrelease) plugin | -| Analyze commits | Determine the type of release to do with the [analyzeCommits](#analyzecommits) plugin | -| Verify release | Call the [verifyRelease](#verifyrelease) plugin | -| Generate notes | Generate release notes with plugin [generateNotes](#generatenotes) | -| Publish | Call the [publish](#publish) plugin | +Here is an example of the release type that will be done based on a commit messages: -## Default Commit Message Format +| Commit message | Release type | +|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| `fix(pencil): stop graphite breaking when too much pressure applied` | Patch Release | +| `feat(pencil): add 'graphiteWidth' option` | ~~Minor~~ Feature Release | +| `perf(pencil): remove graphiteWidth option`

`BREAKING CHANGE: The graphiteWidth option has been removed.`
`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release | -This module ships with the [AngularJS Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit) and changelog generator, but you can [define your own](#plugins) style. +### Automation with CI -Each commit message consists of a **header**, a **body** and a **footer**. The header has a special -format that includes a **type**, a **scope** and a **subject** ([full explanation](https://github.com/stevemao/conventional-changelog-angular/blob/master/convention.md)): +semantic-release is meant to be executed on the CI environment after every successful build on the release branch. This way no human is directly involved in the release process and the releases are guaranteed to be [unromantic and unsentimental](http://sentimentalversioning.org). -``` -(): - - - -