EasyBuild.CommitParser 3.0.0

EasyBuild.Parser

👁 NuGet
👁 alternate text is missing from this package README image

Common commit parser library used by other EasyBuild tools like EasyBuild.ChangelogGen or EasyBuild.CommitLinter.

It aims to provide helpful contextual error messages like:

Example of error messages:

Invalid commit message format.

Expected a commit message with the following format: '<type>[optional scope]: <description>'.

Where <type> is one of the following:

- feat: A new feature
- fix: A bug fix
- ci: Changes to CI/CD configuration
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
- docs: Documentation changes
- test: Adding missing tests or correcting existing tests
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- revert: Reverts a previous commit
- build: Changes that affect the build system or external dependencies

Example:
-------------------------
feat: some description
-------------------------

or

Unkonwn tag(s) in the footer.

Received:

- some-tag

But allowed tags are:

- converter
- web

Usage

open EasyBuild.CommitParser
open EasyBuild.CommitParser.Types

let commitText = "..."

// If you need the commit message information
Parser.tryParseCommitMessage CommitParserConfig.Default commitText
// > it: Result<CommitMessage,string>

// If you just want to validate the commit message
Parser.tryValidateCommitMessage CommitParserConfig.Default commitText
// > it: Result<unit,string>

For the configuration, you can use the default configuration or provide a custom one.

open EasyBuild.CommitParser.Types

// Default configuration
CommitParserConfig.Default

// My custom configuration
{
 Types =
 [
 // ...
 ]
 Tags =
 [
 // ...
 ] |> Some
}

// You can also use a configuration file by passing the JSON content to the included Decoder
open Thoth.Json.Newtonsoft

let configurationJson = "..."

match Decode.fromString CommitParserConfig.decoder configContent with
| Ok config -> config
| Error error ->
 failwithf "Error while parsing the configuration file: %s" error

Commit Format

<type>[optional scope][optional !]: <description>

[optional body]

[optional footer]

• [optional body] is a free-form text.

  This is a single line body.
  

  This is a
  
  multi-line body.
  

• [optional footer] is inspired by git trailer format key: value but also allows key #value

  BREAKING CHANGE: <description>
  Signed-off-by: Alice <alice@example.com>
  Signed-off-by: Bob <bob@example.com>
  Refs #123
  Tag: cli
  

  💡 The Tag footer can be provided multiple times.

Configuration

EasyBuild.CommitParser comes with a default configuration to validate your commit.

The default configuration allows the following commit types with no tags required:

• feat - A new feature
• fix - A bug fix
• ci - Changes to CI/CD configuration
• chore - Changes to the build process or auxiliary tools and libraries such as documentation generation
• docs - Documentation changes
• test - Adding missing tests or correcting existing tests
• style - Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• refactor - A code change that neither fixes a bug nor adds a feature
• perf - A code change that improves performance
• revert - Reverts a previous commit
• build - Changes that affect the build system or external dependencies

If needed, you can provide a custom configuration either by code directly or by using a configuration file using JSON format.

Configuration File Format

The configuration file is a JSON file with the following properties:

types

• Required: ✅
• Type: { name: string, description?: string, skipTagFooter?: bool } []

List of accepted commit types.

tags

• Required: ❌
• Type: string []

List of accepted commit tags.

Examples

{
 "types": [
 { "name": "feat", "description": "A new feature", "skipTagFooter": false },
 { "name": "perf", "description": "A code change that improves performance", "skipTagFooter": false },
 { "name": "fix", "description": "A bug fix", "skipTagFooter": false },
 { "name": "docs", "description": "Documentation changes", "skipTagFooter": false },
 { "name": "test", "description": "Adding missing tests or correcting existing tests", "skipTagFooter": false },
 { "name": "style", "description": "Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)", "skipTagFooter": false },
 { "name": "refactor", "description": "A code change that neither fixes a bug nor adds a feature", "skipTagFooter": false },
 { "name": "ci", "description": "Changes to CI/CD configuration" },
 { "name": "chore", "description": "Changes to the build process or auxiliary tools and libraries such as documentation generation" }
 { "name": "revert", "description": "Reverts a previous commit" }
 { "name": "build", "description": "Changes that affect the build system or external dependencies" }
 ],
 "tags": [
 "cli",
 "converter"
 ]
}