go-conventionalcommits

2020-11-18T00:00:00+00:00
Fu powers to parse your commits!</p> </blockquote>
This repository provides a library to parse your commit messages according to the Conventional Commits v1.0 specification.</p>
Installation§</a> </h2>
go</span> get github.com/leodido/go-conventionalcommits</span></span></code></pre>Docs§</a>
</h2>
The parser/docs</a> directory contains .dot</code> and .png</code> files representing the finite-state machines (FSMs) implementing the parser.</p>
Usage§</a>
</h2>
Parse§</a>
</h3>
Your code base uses only single line commit messages like this one?</p>
feat:</span> awesomeness</span></span></code></pre>
No problem at all since the body and the footer parts are not mandatory:</p>
m</span>,</span> _</span> :=</span> parser</span>.</span>NewMachine</span>().</span>Parse</span>([]</span>byte</span>(</span>`feat: awesomeness`</span>))</span></span></code></pre>Full conventional commit messages§</a>
</h3>
Imagine you have a commit message like this:</p>
docs:</span> correct minor typos</span></span>
</span>
see</span> the issue for details</span></span>
</span>
on</span> docs edits.</span></span>
</span>
Reviewed-by:</span> Z</span></span>
Refs</span> #133</span></span></code></pre>
Go with this:</p>
opts</span> := []</span>conventionalcommits</span>.</span>MachineOption</span>{</span></span>
    WithTypes</span>(</span>conventionalcommits</span>.</span>TypesConventional</span>),</span></span>
}</span></span>
res</span>,</span> err</span> :=</span> parser</span>.</span>NewMachine</span>(</span>opts</span>...).</span>Parse</span>(</span>i</span>)</span></span></code></pre>
Or, more simpler:</p>
res</span>,</span> err</span> :=</span> parser</span>.</span>NewMachine</span>(</span>WithTypes</span>(</span>conventionalcommits</span>.</span>TypesConventional</span>)).</span>Parse</span>(</span>i</span>)</span></span></code></pre>Types§</a>
</h3>
This library provides support for different types sets:</p>

minimal</strong>: fix, feat</li>
conventional</strong>: build, ci, chore, docs, feat, fix, perf, refactor, revert, style, test</li>
falco</strong>: build, ci, chore, docs, feat, fix, perf, new, revert, update, test, rule</li>
</ul>
At the moment, those types are at build time. Which means users can't configure them at runtime.</p>
Anyway, there's also a free-form</strong> types set that accepts any combination of printable characters (before the separator after which the commit description starts) as a valid type.</p>
You can choose the type set passing the WithTypes(conventionalcommits.TypesConventional)</code> option as shown above.</p>
Options§</a>
</h3>
A parser behaviour is configurable by using options.</p>
You can set them calling a function on the parser machine.</p>
p</span> :=</span> parser</span>.</span>NewMachine</span>()</span></span>
p</span>.</span>WithBestEffort</span>()</span></span>
res</span>,</span> err</span> :=</span> p</span>.</span>Parse</span>(</span>i</span>)</span></span></code></pre>
Or you can provide options to NewMachine(...)</code> directly.</p>
p</span> :=</span> parser</span>.</span>NewMachine</span>(</span>WithBestEffort</span>())</span></span>
res</span>,</span> err</span> :=</span> p</span>.</span>Parse</span>(</span>i</span>)</span></span></code></pre>Best effort§</a>
</h3>
The best effort mode will make the parser return what it found until the point it errored out,
if it found (at least) a valid type and a valid description.</p>
Let's make an example.</p>
Suppose this input commit message:</p>
fix:</span> description</span></span>
a</span> blank line is mandatory to start the body part of the commit message!</span></span></code></pre>
The input does not respect the Conventional Commits v1 specification because it lacks a blank line after the description (before the body).</p>
Anyways, if the parser you're using has the best effort mode enabled, you can still obtain some structured data since at least a valid type and description have been found!</p>
res</span>,</span> err</span> :=</span> parser</span>.</span>NewMachine</span>(</span>WithBestEffort</span>()).</span>Parse</span>(</span>i</span>)</span></span></code></pre>
The result will contain a ConventionalCommit</code> struct instance with the Type</code> and the Description</code> fields populated and ignore the rest after the error column.</p>
The parser will still return the error (with the position information), so that you can eventually use it.</p>
Performances§</a>
</h2>
To run the benchmark suite execute the following command.</p>
make</span> bench</span></span></code></pre>
All the parsers have the best effort mode on.</p>
On my machine1</a></sup>, these are the results for the slim</code> parser with the default - ie., minimal</code>, commit message types.</p>
[ok]_minimal______________________________________-12          4876018       242 ns/op     147 B/op       5 allocs/op</span></span>
[ok]_minimal_with_scope___________________________-12          4258562       284 ns/op     163 B/op       6 allocs/op</span></span>
[ok]_minimal_breaking_with_scope__________________-12          4176747       288 ns/op     163 B/op       6 allocs/op</span></span>
[ok]_full_with_50_characters_long_description_____-12          1661618       700 ns/op     288 B/op      10 allocs/op</span></span>
[no]_empty________________________________________-12          4059327       292 ns/op     112 B/op       3 allocs/op</span></span>
[no]_type_but_missing_colon_______________________-12          2701904       444 ns/op     200 B/op       6 allocs/op</span></span>
[no]_type_but_missing_description_________________-12          2207985       539 ns/op     288 B/op       8 allocs/op</span></span>
[no]_type_and_scope_but_missing_description_______-12          1969390       605 ns/op     312 B/op      10 allocs/op</span></span>
[no]_breaking_with_type_and_scope_but_missing_desc-12          1978302       606 ns/op     312 B/op      10 allocs/op</span></span>
[~~]_newline_in_description_______________________-12          2115649       563 ns/op     232 B/op      11 allocs/op</span></span>
[no]_missing_whitespace_in_description____________-12          1997863       595 ns/op     312 B/op      10 allocs/op</span></span></code></pre>
Using another set of commit message types, for example the conventional</code> one, does not have any noticeable impact on performances, as you can see below.</p>
[ok]_minimal______________________________________-12          5297486       228 ns/op     147 B/op       5 allocs/op</span></span>
[ok]_minimal_with_scope___________________________-12          4498694       267 ns/op     163 B/op       6 allocs/op</span></span>
[ok]_minimal_breaking_with_scope__________________-12          4431040       273 ns/op     163 B/op       6 allocs/op</span></span>
[ok]_full_with_50_characters_long_description_____-12          1750111       692 ns/op     288 B/op      10 allocs/op</span></span>
[no]_empty________________________________________-12          3996532       294 ns/op     112 B/op       3 allocs/op</span></span>
[no]_type_but_missing_colon_______________________-12          2657913       451 ns/op     200 B/op       6 allocs/op</span></span>
[no]_type_but_missing_description_________________-12          2172524       553 ns/op     288 B/op       8 allocs/op</span></span>
[no]_type_and_scope_but_missing_description_______-12          1880526       637 ns/op     312 B/op      10 allocs/op</span></span>
[no]_breaking_with_type_and_scope_but_missing_desc-12          1879779       635 ns/op     312 B/op      10 allocs/op</span></span>
[~~]_newline_in_description_______________________-12          2023514       592 ns/op     232 B/op      11 allocs/op</span></span>
[no]_missing_whitespace_in_description____________-12          1883124       623 ns/op     312 B/op      10 allocs/op</span></span></code></pre>
As you may notice, this library is very fast at what it does.</p>
Parsing a commit goes from taking about the same amount of time (~299ns) the half-life of polonium-212 takes2</a></sup> to less than a microsecond.</p>
Build§</a>
</h2>
To build this Go library locally just run:</p>
make</span></span></code></pre>
You'd need Ragel 6.10 to be present into your machine.</p>

[1]</a>: Intel Core i7-8850H CPU @ 2.60GHz</li>
[2]</a>: https://en.wikipedia.org/wiki/nanosecond</a></li>
</ul>
Build §</a> </h2>
To build this Go library locally just run:</p>
`make</span></span></code></pre> You'd need Ragel 6.10 to be present into your machine.</p>[1]</a>: Intel Core i7-8850H CPU @ 2.60GHz</li> [2]</a>: https://en.wikipedia.org/wiki/nanosecond</a></li> </ul>`

leodido.dev - conventional-commits

go-conventionalcommits

Docs §</a> </h2>
The parser/docs</a> directory contains `.dot</code> and .png</code> files representing the finite-state machines (FSMs) implementing the parser.</p>`
