Adopt a convention for highlighting commit messages

[rpatterson]

Magit uses magit-log-propertize-keywords to find parts of the commit message to highlight in log buffers and elsewhere. I find this very useful making it much easier to visually scan long logs to distinguish related commits and find what I'm looking for. Currently, magit-log-propertize-keywords only handles sqaush, fixup or "keywords" in brackets, [foo] .... So I ended up using the latter to make my logs more readable.

Worrying that I was abusing or misusing my commit messages to achieve this, I went looking for any documentation about how one is supposed to use [foo] in git commit messages in the wider VCS community and I was surprised I couldn't really find anything authoritative. So maybe magit should adopt some external, more rigorous convention about commit messages for it's highlighting? When I did a search, I found commitlint which seems to be a pretty good index for references about git commit message conventions that magit might adopt.

[tarsius]

I don't think Magit should enforce some commit message convention beyond the commonly accepted conventions it already (optionally!) enforces. (And it's actually git-commit.el that is doing that.)

I suppose highlighting [...] is a non-standard addition by Magit, but (a) I have seen it done elsewhere (b) it doesn't cause any (or very very minimal) harm for projects that don't use it.

That being said writing some elisp to support e.g. commitlint might be worth it. But that should be done in a separate package (which can use the appropriate hooks provided by git-commit).

[rpatterson]

What I am asking for is about optional highlighting not about linting. IOW, I am proposing we extend or replace the existing [...] highlighting support to highlight the conventional commits specification format for messages. That convention is what commitlint enforces, but I was only mentioning it as a way to point to the convention behind the linter. I've been using these conventions for some time now, so I can better clarify that bit, sorry for the confusion.

I find using this convention has made me a better developer. I've also started using the ecosystem of tools that are growing up around this specification. Tools that use this commit message format to automate versioning and releases: e.g. a push to master parses the commit messages to determine whether to bump the version for a minor or major release, push a tag for that version, and kick off the CD for building the release artifacts. Tools that assemble change logs from parsed commit messages. Etc.. I'm also seeing more and more projects in the wild using conventional commits and such tools.

I think we need conventions for commit messages. I would love it if Magit "encouraged" that by being a better user experience when users follow that convention.

[kyleam]

What I am asking for is about optional highlighting not about linting. IOW, I am proposing we extend or replace the existing [...]

I'd still say a dedicated package would be the way to go for those that like this style. That might require some reworking on Magit's end to make this more customizable, but I don't think that'd be a bad direction to go. These things are super-subjective, so it'd be good to allow people to easily implement their own preferences out of Magit's tree.

(I personally dislike the use of "feat:", "chore:", and so on, but I think I'd say the above even for a style I liked.)

[rpatterson]

These things are super-subjective, so it'd be good to allow people to easily implement their own preferences out of Magit's tree.

I've never seen the [...] convention; I only found it when reading the source behind the face for logs in Magit. I went looking for it or any other convention and conventional commits is the only one I found. So I'd say the [...] highlighting is much more subjective than something that's a well defined specification, widely adopted, and used by a number of tools.

(I personally dislike the use of "feat:", "chore:", and so on, but I think I'd say the above even for a style I liked.)

Why's that, I'd love to hear the argument. I don't like or dislike the specific terms, but I do like that there's something in the commit that says "this change is a new feature and as such should result in a minor release and be included in the Changelog" or "this changes is of no concern to users so doesn't need to trigger a release and should not be included in the changelog". Generally, I don't have an opinion on any of the specifics of conventional commits, only that there is a convention. Reach for a tool to automate your release cycle and tie it to your VCS, you're going to find conventional commits.

[MicahElliott]

I believe the [SOME TAG] convention is from the world of git via email, as in: https://kernelnewbies.org/PatchTipsAndTricks . So it makes sense that magit would do some things to highlight them (and it's great when it does!).Because of magit's highlighting of these, I've been "tagging" commits in this fashion. I agree that it'd be nice to also somehow support the conventions from the spec mentioned with commitlint, and a separate package seems good. I'd adopt the commitlint conventions if magit used them.

Also, relatedly, these icons are nice to have working in magit (since others reading this like this kinda stuff): http://www.modernemacs.com/post/pretty-magit/

[rpatterson]

I believe the [SOME TAG] convention is from the world of git via email, as in: https://kernelnewbies.org/PatchTipsAndTricks . So it makes sense that magit would do some things to highlight them (and it's great when it does!).

Ooh, thanks for making that connection for me! I don't see any reason why both conventions couldn't be supported and highlighted.

Also, relatedly, these icons are nice to have working in magit (since others reading this like this kinda stuff): http://www.modernemacs.com/post/pretty-magit/

Very nice for visually scanning logs! I'd use it if it supported Conventional Commits as well. Fingers crossed.

FWIW, I've written up more about what I've found to be the benefits of using Conventional Commits as I've used the standard more over time.

[maikol-solis]

@rpatterson I'm also interested in some workaround for this issue. If you have any, please let me know. Best.

[rpatterson]

@rpatterson I'm also interested in some workaround for this issue. If you have any, please let me know. Best.

Nope, and I just did a quick google to see if anything has been developed since I last checked and didn't find anything. It's a shame, I'm seeing more and more projects using conventional commits and it would really help scanning the logs to have some smarter highlighting.

[maikol-solis]

@rpatterson I reviewed the function magit-log-propertize-keywords and made some adjustments to include the conventional commits format. It's not perfect, but it should work good enough.

Basically, I added a new while under the magit-log-highligh-keywords to review the commits with the expected format. It took me a while to figure out how to match any possible case, but for me works.

(defun magit-log-propertize-keywords-conventional-commits (_rev msg)
  (let ((boundary 0))
    (when (string-match "^\\(?:squash\\|fixup\\)! " msg boundary)
      (setq boundary (match-end 0))
      (magit--put-face (match-beginning 0) (1- boundary)
                       'magit-keyword-squash msg))
    (when magit-log-highlight-keywords
      ;; Case [...]
      (while (string-match "\\[[^[]*?]" msg boundary)
        (setq boundary (match-end 0))
        (magit--put-face (match-beginning 0) boundary
                         'magit-keyword msg))
      ;; Conventional commits
      (while (string-match "^\\(?:feat\\|fix\\|chore\\|docs\\|style\\|refactor\\|perf\\|test\\)\\(?:\\(?:[(].*[)]\\)\\|\\(?:!\\)\\)?:" msg boundary)
        (setq boundary (match-end 0))
        (magit--put-face (match-beginning 0) boundary
                         'magit-keyword msg))))
  msg)

(advice-add #'magit-log-propertize-keywords :override #'magit-log-propertize-keywords-conventional-commits)

Edit: The code had a missing ?. I fix it and now it should work.