Custom note to explain title-match-regex rule.

[tommyip]

We just re-enabled gitlint at Zulip and a lot of our new students (we are participating in Google Code-in) who aren't comfortable with regex are confused by our ^(.+:\ )?[A-Z].+\.$ rule.

I was thinking if gitlint could show a user-defined note explaining their project's commit title style? I guess we only want to show it once if title-match-regex failed >= 1 time.

I could implement this if you are ok with the proposed feature.

[jorisroovers]

I generally handle things like this using a bash wrapper script - shouldn't be too hard I think.

This ticket together with #53 is making me think more about customization of violation messages. I do think if we do something here, that it should be a generic solution that allows you to customize all violation messages. I'm thinking we should probably extend the use of format parameters as described in #53 to be used in the violation_messages of rules, which can then be overwritten via config.

Don't have time to work on this right now, but maybe something to look into in the future, I'm tagging this as an enhancement.

I obviously welcome your contributions as always, but just a heads up that it might be quite a bit of back and forth because if we do this, I'd like it to be done well and in a generic way. Also, replies/code reviews would take a while as usual...

[jorisroovers]

Every so often I think about this use-case, and I now think I'd like to do this differently then discussed before by supporting user-defined formatters.

Basically, when specifying an --extra-path, as you do when using user-defined rules, gitlint would also discover OutputPrinter classes which can then implement custom output formatting.

Something like this (pseudo-code):

from gitlint.output import OutputPrinter

class MyFancyOutputPrinter(OutputPrinter):
	id="OP1"
	name="my-custom-formatter"

	# We can consider giving OutputPrinters options, configurable via .gitlint
  	options_spec = [IntOption('foo', 3, "My Option")]
	
	def output(event, stdout, stderr):
		if event.type == "start-commit":
			stderr.write("Commit {0}".format(event.commit.sha))
		elif event.type == "found-violation"
			stderr.write("Violation found: {0}".format(event.violation.message))

We can consider adding some out-of-the-box formatters (e.g. the one described in #53 or e.g. a JsonOutputPrinter for easier integration with other tools).

One thing I have thought about is whether I'm not reinventing the wheel here, and maybe we should just use python's logging capabilities for output and then allow users to specify a custom logging.Logger instead. I'll probably need to prototype this and do some research into what other tools like pylint or flake8 do.

I don't see myself working on this in the near future, but probably a bigger feature for one of the following releases.

[sigmavirus24]

I don't know what pylint does, but Flake8 has something akin to what you've designed. That said, rather than using the standard library logger, there's structlog from Hynek that I would recommend because it has the idea of a log line being structured data and being able to format it in different ways (which is pluggable). Passing that responsibility of formatting that to a structlog plugin increases the likely ecosystem and means you just need to know how to register/discover those formatters

I don't know if I would go that direction with Flake8 today if I had the option because of all the old baggage we had, but if I were writing a tool from scratch and I didn't want to offer "pretty" formatting options (e.g., being able to write a formatter that outputs a reStructuredText table, HTML, or something else that requires a bit more logic than I think structlog might be able to offer), then I'd probably go that route.