Setting up semantic-release with commit linter and commit message helper

Setting-up-Semantic-Release.md

Setting up Semantic-Release

Setup based off this article: https://hackernoon.com/these-6-essential-tools-will-maintain-your-npm-modules-for-you-4cbbee88e0cb

Table of Contents

• Setting up Semantic-Release
  • Table of Contents
  • Packages used
  • Steps
    • Install semantic-release
    • Set up commit linter
    • Commit Helper
  • Troubleshooting

Packages used

package	description	why
semantic-release	Fully automated version management and package publishing	handles publishing and changelog generation
marionebl/commitlint	Lint commit messages	allow people to create commits like normal, but be restricted if they don't match expected format
commitzen/cz-cli	The commitizen command line utility.	help people make commits (commitlint has a prompt sub-package @commitlint/prompt, but this one seemed more mature and commitlint still has to improve their prompt (https://github.com/marionebl/commitlint#roadmap))

Steps

Install semantic-release

• make copy of .travis.yml
• use semantic-release-cli: https://github.com/semantic-release/semantic-release/blob/caribou/docs/usage/ci-configuration.md#automatic-setup-with-semantic-release-cli

  $ npx semantic-release-cli setup

  • Answers to Questions:
    • private repo
    • default npm registry
    • npm username: pedro-ifit
    • github username: pedro-mass
    • ci: Travis CI Pro
    • setup .travis.yml: yes
    • overwrite existing: yes
      • made a back-up beforehand to figure out what to copy back over
• Fix version in package.json
  • semantic-release-cli assumes you're starting from 0.0.0-development, so you'll need to switch back to what it was

  IMPORTANT: leave the -development part. semantic-release seems to use it.

• Update generated .travis.yml
  • copy back diff from original .travis.yml that we backed up
    • tweaked it a bit to:
      • use recipe listed in docs: https://github.com/semantic-release/semantic-release/blob/caribou/docs/recipes/travis.md#multiple-node-jobs-configuration
      • explicitly only run on master branch (wasn't sure about that regex is running and this seemed clearer)
  • remove support for node_js: '4'

    semantic-release doesn't support that version

• update script travis-deploy-once to include pro flag

  should look like: "travis-deploy-once": "travis-deploy-once --pro", here's the github issue: semantic-release/travis-deploy-once#52

• Add badge to ReadMe: https://github.com/semantic-release/semantic-release#badge
• Ensure Travis had github authentication environment variable: https://github.com/semantic-release/semantic-release/blob/caribou/docs/usage/ci-configuration.md#authentication
• create a commit

  $ git commit -m "feat(semantic-release): configured semantic-release"

Set up commit linter

Using marionebl/commitlint: https://github.com/marionebl/commitlint (referenced by semantic-release docs: https://github.com/marionebl/commitlint)

• install commitlint: https://github.com/marionebl/commitlint#getting-started
• install husky & set up commit hook: http://marionebl.github.io/commitlint/#/guides-local-setup?id=install-husky
• create a commit and test lint: http://marionebl.github.io/commitlint/#/guides-local-setup?id=test
• actually commit

  $ git commit -m "feat(commitlint): configured commitlint"

• set up linting on travis: http://marionebl.github.io/commitlint/#/guides-ci-setup?id=guide-ci-setup

Commit Helper

Following these new conventions will be a hard shift from the norm. We have the linter in place to enforce, this step is to aid in the creation of commits

Using: https://github.com/commitizen/cz-cli

• follow instructions for project maintainers: https://github.com/commitizen/cz-cli#commitizen-for-project-maintainers

  • if using yarn instead of npm, this step creates a package-lock.json. Delete it and run yarn install to get an updated yarn.lock

• add commitizen/cz-cli as local dependency and create npm script to trigger commit: https://github.com/commitizen/cz-cli#optional-install-and-run-commitizen-locally

  • NOTE: change the default script name to something not commit. This is due to our husky commit hook that'll cause issues. Their docs contain more detail in their note.

• upgrade husky to @next from 0.14

  $ yarn add -D husky@next

  • Why? Current husky hooks fail when being run within an npm script. The next version of husky fixes this.
  • upgrade docs: https://github.com/typicode/husky#upgrading-from-014
  • Github issue: typicode/husky#205
• add commitzen badge: https://github.com/commitizen/cz-cli#congratulations-your-repo-is-commitizen-friendly-time-to-flaunt-it
• let's give it a try
  • stage the files
  • run command to commit

    $ yarn cm

  NOTE: Due to commit hooks, your commit might fail. Luckily once you've resolved the issues, you can re-run your last commit attempt with yarn cm --retry: https://github.com/commitizen/cz-cli#retrying-failed-commits you can save this to an npm script you won't have to remember

Troubleshooting

• fixing an old commit message: https://help.github.com/articles/changing-a-commit-message/#amending-older-or-multiple-commit-messages