semver-demo

Demo showing how compliance with the conventional commit message spec can automate CHANGELOG and semantic version bumps (and more).

1. Table of contents

• 1. Table of contents
• 2. Installation
• 3. Usage
  • 3.1. Git commit message format
    • 3.1.1. type
    • 3.1.2. scope, subject, body, footer, and BREAKING CHANGEs
  • 3.2. Git commit message validation
  • 3.3. Git commit message wizards
  • 3.4. Automated CHANGELOG and semantic versioning
  • 3.5. Putting it into practice
• 4. Contributions
• 5. License

2. Installation

Run the following command in a shell:

$ npm install --save semver-demo

3. Usage

semver-demo demonstrates how software products -- libraries, packages, and applications -- can automate

• CHANGELOG.md generation and updates
• Semantic version and CHANGELOG generation using Git's squash merge and conventional commit messages (aka the AngularJS Git Commit Guidelines).

3.1. Git commit message format

The conventional commit message specification, which is based on the AngularJS Git Commit Guidelines, prescribe a precise, parsable commit message format. This not only encourages succinct and consistent change logs, but also enables automated release management with the standard-version package.

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:

<type>(<scope>): <subject>
<BLANK LINE>
<[body]>
<BLANK LINE>
<footer>

3.1.1. type

types describe the kinds of changes made to a software product. Valid types are:

1. build: Changes to build configuration
2. chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
3. ci: Changes associated with continuous integration and continuous delivery
4. docs: Documentation only changes
5. feat: A new feature
6. fix: A bug fix
7. perf: A code change that improves performance
8. refactor: A code change that neither fixes a bug nor adds a feature
9. revert: Commits that revert to a previous version.
10. style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
11. test: Adding missing or correcting existing tests

3.1.2. scope, subject, body, footer, and BREAKING CHANGEs

The AngularJS Git Commit Guidelines document the other parts of a commit message. Please refer to that document for details.

3.2. Git commit message validation

The package commitplease installs a configurable pre-commit hook that validates commit messages.

3.3. Git commit message wizards

Some teams prefer commitizen, which provides a CLI "wizard" that ensures commit messages are valid.

[]

3.4. Automated CHANGELOG and semantic versioning

standard-version parses Git commit messages to:

• "Bump" your software's semantic version based by parsing the types in your commit messages.

| Type | Semantic version bump | Example | |:-------------------|:-----------------------------|:------------------| | BREAKING CHANGE | MAJOR: v**X.Y.Z | 1.0.0 ⇒ 2.0.0 | | feat | MINOR: vX.Y.Z | 1.0.0 ⇒ 1.1.0 | | fix | PATCH: vX.Y.Z** | 1.0.0 ⇒ 1.0.1 |

• Run git tag with the latest semantic version.
• Generate (or update an existing) CHANGELOG.md. This includes semantic version links to tags and commit links for BREAKING CHANGEs, features, and fixes.

:page_facing_up: semantic-release is another popular tool that automates all release tasks by simply merging source code into the master branch.

3.5. Putting it into practice

3.5.1. Add a change to your software.

3.5.2. Commit with a valid conventional commit message:

feat(qa-gates): automate travis-ci qa-gates and security checks (#5)

1. Build with Travis-CI.
2. Add Coveralls for code coverage reports.
3. Check for Node.js vulnerabilities with the Node Security Program (nsp).
4. Automate code reviews with Codacy.
5. Lint source code with ESLint.
6. Identify dependency drift with David-DM.
7. Grade README.md documentation with ScoreMe.
8. Link to latest release on NPM.
9. Add open-source license badge.

Closes #2

3.5.3.Push to your topic branch.

3.5.4. Ensure your automated pull request

• Builds,
• All tests pass,
• Your coverage threshold is met,
• There are no security vulnerabilities,
• Your documentation is good, and
• Passes any other automated quality gates.

3.5.5. Squash and merge your topic branch into

• develop if you're using the Gitflow Workflow, or
• master if you're using the Git feature branch workflow.

3.5.6. Release your product, e.g.,

$ npm run release -- --dry-run

> [email protected] release /Users/swindle/Projects/github/gregswindle/semver-demo
> standard-version "--dry-run"

✔ bumping version in package.json from 0.0.0 to 0.1.0
✔ created CHANGELOG.md
✔ outputting changes to CHANGELOG.md

---
<a name="0.1.0"></a>
# 0.1.0 (2017-06-21)


\ ### Features

* **qa-gates:** automate travis-ci qa-gates and security checks ([#5](https://github.com/gregswindle/semver-demo/issues/5)) ([8d82c46](https://github.com/gregswindle/semver-demo/commit/8d82c46)), closes [#2](https://github.com/gregswindle/semver-demo/issues/2)
---

✔ committing package.json and CHANGELOG.md
✔ tagging release 0.1.0
ℹ  Run `git push --follow-tags origin master; npm publish` to publish

4. Contributions

:family: We warmly welcome contributors. Check out the guidelines for Contributing to semver-demo and our Contributor Covenant Code of Conduct.

Contributions are stories with a beginning, a middle, and an end, all told through issues and pull requests.

• Peruse open issues or
• Open a new pull request (PR)

5. License

Apache-2.0 © Greg Swindle.