User-specified template file instead of interactive dialog

[matu3ba]

I am writing regarding the reddit conversation we had and will shortly recap the idea to reduce user-time on filling the commit message. Sorry for the long post, but I wanted to make sure what I do mean. This feature would include writing a hopefully very simple grammar to check the templates for conventional commits conformance. The template then can be checked locally and by the CI against commit messages. Please let me know what you think of the idea and what your practical experience is with conventional commits.

The idea

Have a template to create the commit "popup as fulltext" in .conv_commit. The idea is to use parse prefix and postfix to check conformance to the content of the commit message with the following lines (as block). The overall structure is (pseudocode later to be replaced by grammar file):

template-identifier template-name
template-version-identifier template-version
commit-identifier hashrange (first hash or dots - last hash or dots)
block-identifier expression; text for user; (amount lines)
optional definitions for expression
default-user space
...
block-identifier expression; text for user; (amount of lines)
(default-user space)
(default-user space)
(default-user space)

template-version here defines the version of git-scm the template was created with. Incompatibilities/CVEs etc then can be checked at startup. One instance of such template, we call it bug.convcom, could look like

template bugs
version 0.0.1
commits [initialhash - ..]
fix(scope): #issuenr;; (1 lines)

freetext; long description, additional informations, etc; ([0-x] lines)

key: #value; fixed and closed issues; ([1-x] lines)
key isof {Fixes, Closes, PR-Close}

Comma-separated values and line-separated keys are implicit knowledge, so not part of the template. Annoyingly hard would be the parsing of expressions key isof {Fixes, Closes, PR-Close}, so saving these as part of the program could be easier for maintenance.

The user would see the following, (I do assume we can somehow make sure the commit is rebased against master, so the according script-template will be executed or an error message returned)

#fix(scope): #issuenr;; (1 lines)

#      freetext; long description, additional informations, etc; ([0-x] lines)

#key: #value; fixed and closed issues; ([1-x] lines)
#key isof {Fixes, Closes, PR-Close}

The empty space is to indicate, that freetext is no keyword. Aside of that the user should only care about the template, when issues occur.

[matu3ba]

@SirWindfield ping.

[mainrs]

Thanks for the ping, I did actually forget to answer :)

So after reading this a couple of times I think I got it. Your idea sounds more like something that is useful in cases where the template does change during the lifecycle of the application or is introduced into one that did not rely on a commit message convention. Especially by declaring the commit hash range, templates can be applied to different ranges of the (pre-existing) commits inside a repository.

The way I understood it is that you can define templates for various types of commits, let's just go with the two mandatory ones, feat and fix. In that case you'd have two templates, one that matches the feature and one the fix commits. Each has metadata that can be used to match it against the right commits (the hash range). The tool would then warn the user if a commit has a matching template but is not formatted accordingly.

Given the fix example you gave, I understood it that fix templates would be allowed to only have footers of type Fixes, Closes, PR-Close. Everything else would be interpreted as false and the tool could return an error/abort/whatever. The body has no restrictions set to it, but the description does. It is only allowed to be one line long. So this would fail to lint correctly:

fix(scope): this is a message
split into two lines

Is that correct? :)

[matu3ba]

Yes, you nailed it. Conventional commits does not specify the body of keywords.

And I wanted to force the text for the user to be as short as possible for a MVP. How do you want to proceed on this?

[mainrs]

It sounds like a neat feature to be honest and I like it! I will probably implement something along the lines of this. I am currently cleaning up all the code that I want to publish to @conventional-commits-rs before I proceed on working on this program :)

I currently want to push and publish all the necessary crates to work inside the conventional commits ecosystem for Rust. After that, I will go back and improve this crate as well. In it's current state, it works with conventional commits and that was my main goal :)

That being said, I need to keep somewhere track on stuff that might be useful inside this tool. This is, however, a feature I am looking into implementing. I am not sure though if I will put it in here or into https://github.com/conventional-commits-rs/commitlint.