Hi all, thanks for reading and responding! I’ll just reply once since the replies raise related points (and I don’t have anything to add where Maxim already replied!).
pinoaffe and Andreas mention we shouldn’t drop the format without introducing a new one. What I’m proposing is not blocking reviews on a ChangeLog-style file listing but otherwise continuing to follow the rest of the guidelines put forth in [GNU’s guidelines] or [Linux’s guidelines]. <https://cbea.ms/git-commit/> is another classic recommendation (although the CLI tip at the end indicates he hasn’t had the pleasure of working with Magit 🐃). For example, reusing the [fzf commit] I mentioned, I would only drop the ‘* gnu/packages/terminals.scm’ line and leave the summary, body, and trailers. In terms of format, <https://commit.style/> covers it. The point is there’s no syntax-heavy format to contend with. IMO, Linux’s guidelines are a bit more germane than GNU’s. Since they presume Git, they don’t suggest describing the “what” in your commit message, since that is in the associated diff, unlike old-school changelog files. For me, a good commit message is just terse prose establishing context for the change that is not obvious from the diff or summary line. The structure is already covered by the diff and diffstat (‘git diff –stat’). Plus some trailers if necessary. But Linux’s guidelines also blather on about Linux-specific concerns like email and the DCO. So perhaps we do need our own brief guidelines. I can open a PR where we can discuss the finer details, since it seems people are open to the general ideas. If it proves contentious we can close it and fall back to a GCD. But I’ll wait on any of that to allow for casual discussion to proceed here. Noé Lopez <noelo...@free.fr> writes: > Great message! Thank you! > In the commits you link, I think the issue is that they are going into > too much details in the function(module) part. > > For example with > <https://codeberg.org/guix/guix/commit/ce10e2b3e93476a89cf85838fa21bb8b54268b1f>. > It > could mostly be: > > * gnu/packages/game-development.scm (tsukundere) > gnu/packages/gimp.scm (glimpse) > gnu/packages/gnunet.scm (gnunet) > gnu/packages/guile-xyz.scm (guile-bash, guile-filesystem) > (guile-ics, guile-udev) > gnu/packages/logging.scm (glog) > gnu/packages/mail.scm (libetpan) > gnu/packages/mate.scm (mate-icon-theme-faenza) > gnu/packages/package-management.scm (guix) > gnu/packages/sawfish.scm (librep) > gnu/packages/video.scm (motion) > gnu/packages/zile.scm (zile): > Use “autoconf” instead of “autoconf-wrapper”: likewise. Thanks for describing your usage! Here are my impressions. For this commit, I would again just drop the ‘* gnu/’ lines. Even with the simplification, it’s restating the diff. The target audience for commit messages is developers who can be expected to read source code. When you scroll through the diff, it’s immediately evident that in ‘gnu/packages/video.scm’, ‘autoconf-wrapper’ is replaced with ‘autoconf’. It’s also already in the summary line. > Yes, its still a lot of lines, but I like that it forces me to explain > every change that was made. I would humbly suggest that “Use “autoconf” instead of “autoconf-wrapper”” is not doing much explaining when the diff looks like this: ┌──── │ - `(("autoconf" ,autoconf-wrapper) │ + `(("autoconf" ,autoconf) └──── In a case like this, the summary line is sufficient to explain every change that was made. In the time it takes to read the file listing, you can get more out of reading the actual diff. The commit message’s purpose isn’t to enable people to avoid reading the diff; that’s an impossible goal. It’s to contextualize the diff. > In my opinion, the format helps me with writing good commit messages. > > The most important things in my opinion is it allows to describe the > changes bit-by-bit. So I don’t have to say ”In function X of file Y” or > “Add X to module Y”, I can just say “function(module): Do this.”. IMO you don’t have to say any of those things! 😄 > It’s very easy for me to make a related two lines change in a function > to support my use case and put it in a commit. Now no one knows why the > function was changed, since the commit talks about the main change only. If you can provide an example here, I can try to provide how I’d write a commit message. But to attempt to respond to the general case you describe, I think commit messages should definitely make mention of ancillary changes in a commit when the rationale isn’t self-evident to a programmer with basic familiarity with the project. I can try to use the autoconf commit as an example. While most of the changes are covered by “gnu: Use autoconf instead of autoconf-wrapper when possible”, there are also some comments added where autoconf-wrapper couldn’t be replaced. So in the commit message, you might add something like “Where autoconf-wrapper can’t be replaced, comment why it’s necessary.” But in this case, I think any developer reading the diff is going to immediately understand the intent of the comments, so it’s not worth mentioning here. But the same general approach can be taken with ancillary changes which aren’t simple comments (and reviewers can and should make requests when something isn’t clear to them). > Anyways, I’m for simplifying the format for our use case, but let’s not > drop it entirely. I think overall our commits look great so its > definitely working nicely. This is partly why I didn’t propose banning the format outright in my original message. I don’t want to bother developers who like writing the current style (other than the fact that they’ll need to get used to seeing commits from others without the rote file enumerations). > Also I’m biased by using the generate-changelog-message from Magit. I’m > sure I would hate the format if I had to write everything by hand. What I’m proposing is not a “format” per se but simple prose, so there’s nothing to generate (LLMs notwithstanding…). In fact, a useful rule of thumb is that if part of a commit message can be generated from the diff, it probably isn’t useful information! Occasionally the high-quality Emacs integrations Guix has can mask the fact that the work being automated is not necessary, so all we end up with is an ever-heightening barrier to entry for non-Emacs users. Not to go off on another tangent, but I think the indent rules are another example of this. IMO time spent yak shaving directory-local scheme-indent-function values should be invested in guix style. >> PS: I’d really like to drop the double space requirement, too > > Yes! While I’m on the topic, the other FTCX stumbling block is ending the subject line with a period. It’s another case where nobody else does it. And I do see reviews mention it. Oops, another screed. Well, thanks again for reading! —Liam [GNU’s guidelines] <https://www.gnu.org/prep/standards/html_node/Change-Logs.html> [Linux’s guidelines] <https://www.kernel.org/doc/html/latest/process/submitting-patches.html> [fzf commit] <https://codeberg.org/guix/guix/commit/36dc401bbd1a2081d25cfe6491f7aadb9e71d99d>
