Table of Contents

• cc
  • Changelog CLI
    • Installation
    • Configuration
    • Usage
    • Markdown
    • Github Actions
  • Library

cc

A small go library to parse conventional commits and a cli to create a changelogs.

Changelog CLI

The changelog cli creates and updates CHANGELOG.md markdown files.

Installation

You can download a precompiled binary from the releases page or install it with go:

$ go install github.com/zbindenren/cc/cmd/changelog@latest

Configuration

You can create a default changelog configuration .cc.yml with changelog -init-config. This results in the following configuration:

sections:
    - type: build
      title: Build System
      hidden: true
    - type: docs
      title: Documentation
      hidden: true
    - type: feat
      title: New Features
      hidden: false
    - type: fix
      title: Bug Fixes
      hidden: false
    - type: refactor
      title: Code Refactoring
      hidden: true
    - type: test
      title: Test
      hidden: true
    - type: chore
      title: Tasks
      hidden: true
github_project_path: ""

Hidden sections will not show up in the resulting changelog. The default configuration creates Gitlab Markdown. If your our project is on Github, you have to add the project path to .cc.yml:

github_project_path: zbindenren/cc

Usage

To create a new release run:

$ changelog
last version: 0.2.1
next version: 0.3.0
create release 0.3.0 (press enter to continue with this version or enter version):

The proposed version corresponds to Semantic Versioning, but you can override the version, by entering a different one. The entered version can not be below the current version.

The above command then performs the following tasks:

• creates or update CHANGELOG.md file
• stages (if necessary) and commits the changes
• create a new version tag
• and pushes everthing to remote

If you just want to see what happens, you can run changelog -stdout. With this option, no changes are applied to the git repository.

If you have already release tags in your project, you can create the old changelog with: changelog -history > CHANGELOG.md. The history command always prints to stdout and performs no commits.

To see all available options run: changelog -h.

Markdown

Commits of the form:

feat(compiler): add 'comments' option

feat: add a new feature

lead to following Markdown:

### New Features

* **common** add a new feature ([a1f6009e](https://github.com/zbindenren/cc/commit/a1f6009e))
* **compiler** add 'comments' option  ([aecbc18b](https://github.com/zbindenren/cc/commit/aecbc18b))

If you add a footer with a issue reference Closes: #1 or Fixes: #1 like:

fix: a bug

Closes: #1

you get the following markdown:

### Bug Fixes

* **common** fix a bug ([#1](https://github.com/zbindenren/cc/issues/#1), [a1f6009e](https://github.com/zbindenren/cc/commit/a1f6009e))

If you commit breaking changes:

feat(server-cmd)!: remove option -a

feat(client-cmd): remove option -b

BREAKING CHANGE: this change is introduced because ...

you get the following markdown:

### Breaking Changes

* **server-cmd** remove option -a ([a1f6009e](https://github.com/zbindenren/cc/commit/a1f6009e))
* **client-cmd** remove option -b ([a1f6009e](https://github.com/zbindenren/cc/commit/a1f6009e))
  > this change is introduced because ...

An example can be found here.

Github Actions

Here is an example how you can use the changlog tool to verify conventional commits in a github action: conventional-commits.yml

Library

Instead of regular expressions, this package uses a lexer, that functions similarly to Rob Pike's discussion about lexer design in this talk.

This library, parses a commit of the form:

fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

into a struct:

&cc.Commit{
  Header: cc.Header{
    Type: "fix",
    Scope: "",
    Description: "correct minor typos in code",
  },
  Body: "see the issue for details\n\non typos fixed.",
  Footer: cc.Footers{
    cc.Footer{
      Token: "Reviewed-by",
      Value: "Z",
    },
    cc.Footer{
      Token: "Refs",
      Value: "#133",
    },
  },
}