13 ms·

Subject-First Commit Messages

151 points by s4i 3y ago

torton 3y ago
Meh, as in this doesn’t feel like it really matters. Like other commenters, there are exceptionally few situations when I find myself just reading the commit log, so the claimed psychological advantage appears moot in the context of the common/standard software development process (which is very much not what author’s team does, so I acknowledge this approach brings specific measurable advantages for them). When I do need to read the commit log, it’s typically for a third party component and I look for broad categories I need to pay attention to (security fix? Behaviour change?) — this aligns well with the conventional commits standard and well managed release notes. But, to not have to read commit logs, we also do the rest of the conventional software development workflow (PRs, team meetings, etc) that serves to build the awareness of what’s being done.
TacticalCoder 3y ago
I like to be able to read the commit line following the sentence: "This commit shall ...". For example from TFA: "Fix code example in the field_name method" gives: "This commit shall fix code example in the field_name method". OK, cool, I may or may not merge it, pull it, whatever-it. But I know what it'll do should I use it. Now from what TFA recommends: "Default reader batch size is 1000" Means nothing. Tells nothing. Is 1000 good or bad? No clue. Is it causing a bug? A performance issue? Was it 1000 before the commit or after applying it? Zero information. I'll pass and keep using the "best practice". Using the best practices the commit would read: "Change default reader batch size to 500" or "Change default reader batch size to 1000" or maybe "Add default reader batch size" (btw the commit line in TFA is so bad that I'm not sure at all it's 500 or 1000 or something else I should put here to make my point). The "best practices" aren't a bias. They're the result of people thinking long and hard as to how to make commit lines as clear as possible. I look at how multi-million lines codebase like Linux or Emacs are doing it and use that as the authority. If it works well enough for these projects, it works well enough for smaller projects.
- hmeh 3y ago
  > I like to be able to read the commit line following the sentence: "This commit shall ...". I'd guess there's a near zero chance you do this when looking at (scanning) a list of commits. This is a mnemonic for writing commit messages in the commonly accepted style. If you do that in order to help you understand a commit message every time you read one, that may be a personal thing. > Means nothing. Tells nothing. Is 1000 good or bad? No clue. Is it causing a bug? A performance issue? Was it 1000 before the commit or after applying it? Zero information. > Using the best practices the commit would read: > "Change default reader batch size to 500" or "Change default reader batch size to 1000" You realized you could ask the same questions about the versions you put forward, yes? Aside from the "Was it 1000 before the commit..." which, on our team, would be such a ridiculous question it wouldn't even enter the mind. As I said somewhere else, the headline for a celebrity dying does not ever read: "Some Celebrity Is Sick" > I'll pass and keep using the "best practice". Works for me :) > I look at how multi-million lines codebase like Linux or Emacs are doing it and use that as the authority. If it works well enough for these projects, it works well enough for smaller projects. Linux and Emacs have completely different circumstances than most software projects. The idea that cargo culting their practices is good for "smaller projects" is exactly why I wrote my article on best practices. By the way, I contribute to Emacs and I don't find their particular commit message format good or useful. It's particularly onerous, redundant, and does not tend to provide useful additional information (in particular the mandated change log portions -- people do often supply additional information, which can be useful). I tend to find the devel list and bug list more useful for the context of a change, which fits with our experience as well with work logs and project logs.
rco8786 3y ago
I think I would prefer this style. And also the discourse around commit messages and their various flavors may be one of the biggest wastes of time in terms of ROI in our industry. I’ve been doing this for 14-15 years and can probably count on two hands the number of times I’ve needed to look at historical commit messages.
- naavis 3y ago
  I don't know, I do it almost daily. So your mileage may vary.
  - sverhagen 3y ago
    I do it almost daily too. What _is_ rare, is finding a commit message that tells me anything useful that I couldn't have derived from the diff also. I don't need your life story, but sometimes some context about why something was needed is great.
    - rco8786 3y ago
      Exactly. Im in git history all the time. But the messages themselves…eh. Im basically always looking for a change in a specific file or set of files, and then I just pull up the diffs.
    - madeofpalk 3y ago
      What I do find useful is the subject/area, and the author.
    - hmeh 3y ago
      Author here. Yes, the diff should tell you more, but you shouldn't need to look at the diff until you have an idea what the contents of that diff are about. It's like the links on the hacker news home page -- clicking them will always tell you more, but the index should be geared for the use case, which is scanning, typically.
      - sverhagen 3y ago
atoav 3y ago
Bottom line first. I like it.
henning 3y ago
Like everything in software development, this is just personal preference without any actual evidence, a substitute for actually making software with quantitative quality metrics that users actually care about. Let's fiddle with our commit messages, PR formats, code formatting, etc. etc. etc. instead of addressing the fact that our website has 6 different fonts and makes 30 HTTP requests to show a few hundred bytes of text.
- idlephysicist 3y ago
  I totally agree, I have seen people get so fixated on this in addition to: - review feedback format - variable naming - keeping line lengths to 80 lines - log message formats (sweet jesus the amount of time wasted debating that alone) Whenever I see these conventions about commit formatting they generally seem to focus on the first line (notable exceptions being Git and the Linux kernel among others I assume), one line is rarely enough to describe the change – I’m not advocating for writing an essay for a 5 line change though in some cases it might be warranted. Professionally I rarely see useful commit messages, by useful I mean something that could be read by someone without context and get a general understanding of why a change was made. Frequently I have seen “updates” / “wip” etc. in the master branch. More frequently I see that the quality of commit message decreases with an engineer’s seniority – though like every thing there are exceptions.
- hmeh 3y ago
  Author here. You're well within your rights to believe it is personal preference, but it's somewhat hard to refute the fact that it's easier to scan lists when you put the most significant (i.e., the part that varies the most) first. Imagine if every item on Amazon's list of products was of the format: "Product for purchase, Headphone, Sennheiser Momentum 4"
egnehots 3y ago
there are pros and cons to both verb-first and subject-first commit styles. verb-first commits can be organised in a few categories. since they are few commit verbs (fix, add, refact..), always use the same verb prefix for bug, features messages and you will have nice categories to scan/filter: - add feature - fix bug - refactor logic On the other hand, subject-first indeed put the important part first and let you search for a term: - Instance configure template method called from constructor - Store's project method is an alias for fetch - Title is changed Depending on the use case, are you often searching for something? or would you like to highligh the nb of bugs/features in the last release?, one style is better suited than the other. For important changes, I like the linux kernel style: oneline summary, details (problem, impact, solution..) https://docs.kernel.org/process/submitting-patches.html https://docs.kernel.org/process/submitting-patches.html
laerus 3y ago
After started using conventional commits [1] for my messages the style of Subject-First commit messages comes almost naturally. [1] https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/
Salgat 3y ago
In my experience consistency is more important than any specific style of commit messages. Similar to style guides for code; there's plenty of ways to approach it, but the real value is the consistency in how things are written across all developers.
tahnyall 3y ago
I prefer the first version, I didn't find the second version to be more "scannable" and it seems to me to be more esoteric requiring study to realize what was recorded. The first version is clear, each commit makes sense and is what I'd be grepping for when trying to find a commit.
knorker 3y ago
This seems super subjective, while being written as if it's not. I find this way WAY harder to read/scan, and very much prefer Google's standard: https://google.github.io/eng-practices/review/developer/cl-descriptions.html https://google.github.io/eng-practices/review/developer/cl-d...
- davidmurdoch 3y ago
  What is CL here?
  - king_geedorah 3y ago
    CL stands for change list. https://google.github.io/eng-practices/ https://google.github.io/eng-practices/
  - tuwtuwtuwtuw 3y ago
    Change List. Similar to pull request I think.
  - tsimionescu 3y ago
    "Change List", Perforce's name for the rough equivalent of a commit. It's called a change list even though it's a single commit because Perforce tracks changes per file, so if you modify multiple files in a single commit, you are introducing a list of changes in their model.
  - deleted 3y ago
    [deleted]
  - deleted 3y ago
    [deleted]
  - deleted 3y ago
    [deleted]
  - knorker 3y ago
    Sorry, yeah I should have clarified that. For the purposes of the topic at hand, "CL" is "commit".
asylteltine 3y ago
This doesn’t work with conventional commits which is flat out awesome. But I will try mixing both because I like the idea
ikari_pl 3y ago
Error messages. Get to the meat of it in the first 3 words, there's a high chance that's the only part that will get read, or even displayed. It must be the most meaningful part of the error message.
twodave 3y ago
I look at commit messages every day. I actually don't love a message that just describes the code change (I can figure that out on my own if I look at it long enough). That's fine for bigger or more misleading changes, but when I'm looking at blame/history I'm usually very aware of what the code is doing already. My question at those times is less about "what" and more about "why". Why was this change made? Sometimes that can be found by looking at accompanying tests (if the original author was so gracious), but if it's not in the commit (or only obtusely so, as many developers I know tend to commit in what I'll call "stream-of-consciousness" style) then I've got to go outside the codebase to research by interviewing people (assuming they're still around and remember) or trawling through our project management system to try and line up released features/fixes with the change. It quickly becomes an inexact science. That said, in my experience, the larger an organization, the more commit messages get looked at. On my side projects where only 1-3 people are involved, commit messages only really show up on the PRs as things are going in. Sometimes we complete our own PRs to keep up the velocity since we're all working async part-time. Rarely if ever do we look back to figure out why we did something because the project is so small.
- BoxFour 3y ago
  > My question at those times is less about "what" and more about "why". Why was this change made? Isn't the essence of the commit message body to delve into the 'why'? The ability to swiftly glean the 'what' from the commit subject line aids in identifying the appropriate commit for review. The commit message body can then have a detailed explanation of the reasons behind the change.
  - jbverschoor 3y ago
    The diff is the what. Putting what in the message is fluff to make gatekeepers happy
    - masklinn 3y ago
      Disagree. Putting "what" in the message can be fluff, in the same way repeating the code in a comment is fluff. But the broad strokes or considerations of the what may not be obvious from the diff. Expressing what the commit intends as prose can help with understanding, with discarding irrelevant change data, with post-mortem analysis, ...
andai 3y ago
Spent 5 minutes trying to figure out where field_name is in the second list... I thought it was the same commits rewritten to be more scannable, but they are from a different project. (I scanned, naturally, the article itself!) Or more generally, I thought the point of the article would be that the function / variable names from the first list would be moved to the beginning of sentences. But in the 2nd example they are completely absent, favoring much vaguer / high level descriptions. So we are unable to see the before/after effect for the same list of commits, I think most of the potential impact of the author's intended point is lost. (Also, the first half extolls the virtues of being able to read quickly, while the second half tells you to use longer sentences for everything for apparently no reason?)
- hmeh 3y ago
  Author here. I chose two real sets of commit messages rather than to fabricate one. Fabricating one may have made the second list easier to scan -- you'd already know what you were looking for and you would have some familiarity with the content. In any case, it's certainly not a perfect experiment or demonstration. The specific function/variable names do not often make appearances in our commit messages (though they do sometimes, as do class names). They do, however, make very clear appearances in diffs. Commit messages stand on their own for their own purpose -- it's an index, and indexes are for scanning. If you need to read further, you zoom in. Also, I wasn't trying to say to "use longer sentences for everything," where did you get that from? I offered some specific clarifications on how we write some common commit messages, and they may be longer than some alternatives, but our reasons are for clarity and consistency. We don't mind slightly longer commit messages, in large part because the first few words tend to be the most important.
r3trohack3r 3y ago
I personally prefer conventional commits. https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ The subject line says what the purpose of the change is (CI/CD, tests, bug fix, new feauture), what component it primarily focuses on, and then a plain text one line summary. For example: ci(GitLab): Add rust build directory to cache This should improve build times by caching most of the compile tree between builds. In testing, I’ve observed builds drop from 2m to 30s when scheduled on a node with a primed cache. It also forces me to keep my commits focused. If I can’t create a one line summary of what I’ve done, it probably needs to be broken up into multiple commits.
- ericrallen 3y ago
  Conventional commits are great, especially if you add in commit linting. Being able to programmatically increment semantic versions and automatically generate relevant changelogs is awesome. It’s also nice to implement Commitizen[0] for a little hand holding until folks get used to the linting. I used to care a lot about doing things the way that felt right to me, but now I just want some common standard that is easy for everyone to follow, easy to automate, and easy to verify programmatically. Things like conventional commits and semantic versioning aren’t perfect, but they are quite good and apply broadly to many use cases with common tooling and conventions. -- [0]: http://commitizen.github.io/cz-cli/ http://commitizen.github.io/cz-cli/
- diarrhea 3y ago
  But they’re not mutually exclusive. The two concepts play well together!
- rzzzt 3y ago
  I find the word choice for types "feat" and "chore" infuriating for some reason. Feat?!
  - SergeAx 3y ago
    "feat" is something that adds value to product's end users. The things we put on release notes. "chore" is something that adds value to the engineering team. The things we have to do to keep being productive.
isratjahan 3y ago
I like the first concept.
minimaul 3y ago
I like a style like: codebase section: short summary longer description if necessary eg: cocoaui: fix images being incorrectly aligned on high dpi displays We were calculating the position of the image in logical pixels, but not converting that to actual display pixels for rendering. I think it's a really nice style that makes commit messages really easy to scan in a short log, and lets you ignore commits easily that don't touch the area you're interested in
reactordev 3y ago
I’m against any style or enforcement of style of commit messages that breaks changelog I use git log history for changelogs with a little dressing for markdown. I could pull this from Jira but it’s worse. Stories aren’t changes. So I understand that some folks use git log for history and care about their code style so much as to enforce commit message stylecop, it’s overkill in my world and would only cause you to have to amend your commit or write a new message on squash.
gherkinnn 3y ago
The subject-first style felt grating at first, but comparing the two I found myself reading more per line than I did in the verb-first approach. Fix skip fix skip fix skip add skip I knew nothing at the end. The second style had me grasp more, as there were no obvious hooks to skip without knowing what had changed. But as others have said, commit messages are a cesspool of bikeshedding and ultimately useless, unless every commit is a self-contained chunk of work which it rarely is. On the side, I enjoyed all of this author's thoughts in the repo. Good find.
- hmeh 3y ago
  Author here. Thank you! I agree that there can be plenty of bike shedding about them, which is why we have an approach that is based on human psychology and can be backed up in that way. We don't often put too much more in the content of a commit message -- the diff, plus the repo it's in (we have many repos) tell you most what what you need to know. If you want more context, every team member has a daily work log that is available to the entire team, so you can see more about what they worked on and why in that work log.
  - pseudalopex 3y ago
    > I agree that there can be plenty of bike shedding about them, which is why we have an approach that is based on human psychology and can be backed up in that way. You optimized for a micro benchmark and presented no data.
    - hmeh 3y ago
      It was a design decision, and like most design decisions, it was based on first principles and a-priori knowledge. If we had to base all of our design decisions on data and benchmarks, we wouldn’t be able to design anything. I can assure you, that if a better format with better properties came around, we would likely switch to it (assuming we accounted for switching cost and the variation we would be introducing).
vitus 3y ago
> The second style likely feels foreign, and possibly uncomfortable. It's passive voice and present tense — all the things that we aren't supposed to make our commit messages. Nitpick: it's passive voice and indicative mood (and sometimes subjunctive) -- there's nothing wrong with present tense. "Fix typo" is active voice, present tense, and imperative mood. (The Rails commits that dip into past tense bother me slightly, but whatever.) Broadly, I have a few opinions on commit messages. The style doesn't really matter as much to me, although I'm a relatively strong adherent to "one-line summary, followed by paragraph(s) of additional context" (as is standard in the Linux kernel, and supposed best practice at Google even if it isn't universal by a long shot). One is that the commit message should be useful for anchoring a search for potentially relevant changes, and for providing broader context re: why the change was made. At the same time, I waffle between putting more description in the commit message, versus just commenting the code (or making the code clearer). The last is more pragmatic: when I'm searching for a specific change, I'm often looking at the history of a particular file (blame or otherwise). I can quickly filter out all the "fix typo" messages or "[LSC]" (large-scale change, term used at Google for various company-wide code health refactors). Or if I'm trying to figure out which change introduced a bug, I'll probably bisect it one way or another (I often try to short-circuit that bisection toward the end to save the last few iterations). Either way, I don't actually spend that much time reading through commit messages until I've identified a potentially problematic change.
- deleted 3y ago
  [deleted]
- n_plus_1_acc 3y ago
  Around half of them are actually avtive voice, like "Snapshot interval build argument overrides ..."
- hmeh 3y ago
  Author here. Thank you, updated. We don't tend to put much in the commit messages themselves. The code often speaks for itself (and if it doesn't, it isn't likely that the author would have had much more to say about it at the time, as our norm is to comment "why" when necessary). We also have work logs we can refer to that sometimes have the why, or at least some of the context for the work we are better trying to understand.
graypegg 3y ago
Past commit messages have 2 uses to me. - Blame view, where I usually want to know the ticket number so I can track down a story which has the business rules the dev was implementing. - Bisect, where I want to know if this works or not without having to do a test run every time. This format is alright I guess, but the best thing you can do honestly is just TICKET: [done/works but wip/does not work] [describe what you’re thinking] AB-1234: does not work, trying to rewrite this controller to remove all the duplication, /api removed temporarily To me, that doesn’t have to be set in stone. No one likes working with a commit message stickler when standardized formats are only useful ~20 times a year to save 10 minutes each. (In my experience)
vlovich123 3y ago
The problem with the experiment is that when I’m scanning, typically I’m never scanning and then getting tested on the contents after the fact. It actually took me longer to spot any mention of store in the second example after being told what I was looking for than it did for me to find field_name after being told to look for it. YMMV.
gavinhoward 3y ago
Strong disagree. Commits are actions and should place actions first. If you need to find a specific item, that is what `git log --grep` is for.
- hmeh 3y ago
  Author here. Commits aren't actions -- they are a log of an action being taken. You, the committer, are committing. What you commit, goes into a commit log. We choose to make our commit messages describe the change, rather than the person that made the change. It's about the work, not the worker.
  - gavinhoward 3y ago
    And the work does an action on the code.
    - hmeh 3y ago
      I'm trying to imagine my commits coming alive and doing things to my code. I think you may be taking the "When this commit is merged..." thing a bit far, as commits don't actually do anything. They just are. We don't tend to do ourselves any services by anthropomorphizing aspects of our work. I'm happy to concede that we see things very differently.
      - avgcorrection 3y ago
        It has nothing to do with anthropomorphizing. The Git project uses the style of: Refactor x As in: command (verb: refactor) the code to change in this way. That a person wrote the code is irrelevant.
        hmeh 3y ago
        I was responding to the author of the comment I was responding to, who was anthropomorphizing the commit itself claiming that it did something. I agree that the person who write the code is irrelevant, though I realize that in a different way. I also recognize that it varies from Git/Linux/etc. We do it for usability and other reasons and one only needs to look at git itself to recognize that the original authors did not have usability in mind when designing it. What they built is incredibly powerful, but it's rare for usability and technical prowess to overlap.
deleted 3y ago
[deleted]
turtleyacht 3y ago
Verb-first is already the subject. We fill in the latter portion of a sentence that begins (in our head), "When merged, this commit will..."
IshKebab 3y ago
I prefer the first style. It reads way less weirdly. I spend way more time reading commit messages than "manually searching" by scanning them. I either arrive at the commit from git blame, or I use this really cool feature of computers called "ctrl-F".
Groxx 3y ago
Ehhh... maybe. One implicit trade-off here is how low detail the second set is, and that'll happen any time you force a structure - mandated structure takes more space on average, sometimes significantly more. Passive voice wastes a lot of space too (in English anyway). Personally I think this is better solved by a changelog doc (which you can wordsmith for outsiders, which is an entirely different target than internal developers) and `git blame` (I never browse all of history to find changes to a method, just blame it for the latest or `git log -p -L` to check a series of changes to a file/func/etc).
hn_throwaway_99 3y ago
TBH, at least at every company I've worked at recently, the style of the commits is more or less irrelevant to me save for one very important piece: The commit starts with the ID of the ticket for the code change (or some placeholder for very small commits where a ticket wasn't necessary, e.g. [no-tix]). The biggest benefit of this is that these commits can then be automatically linked to the ticket which often has a lot more detail and conversation. 99% of the time when I'm looking at commit history, I'm not just generically scanning. I'm usually looking for a particular change, or when something touched a particular file, etc. Even the example given in the linked page isn't really relevant to me, because I'm rarely "quickly scanning" a whole commit log for something in particular - I'd always just use a search feature (in GitHub or some git IDE plugin) for that.
- avgcorrection 3y ago
  I agree that the ticket id should go somewhere in the commit message. Certainly if things like pull requests are tied to tickets. However I get a little concerned that such sentiments are so popular here. Because the ticket id is a nice contextual link. But the commit message should be self-contained with regards to the change.[1] It’s a version control system. That includes an explanation as well. The explanation for each revision is integral. And I don’t think people here really disagree with that. Just that they might prefer to put all that integral information somewhere else—the information (princess) is in another castle, Mario. Why? Why not at least just copy-paste the relevant information into the version control system proper? I see this all the time; people often do the same with GitHub pull requests—paragraphs upon paragraphs in the pull request description and then just a “Merge <convoluted URL>” in the merge commit message! It’s not that I blame people for this. Maybe Git is just so unergonomic that many would prefer to offload everything into another interface (even Jira). [1] My tickets will usually have all the history. Maybe a lot of back and forth. The commit message though will just have what was done when all was said and done—no back and forth, just the result. And some of my tickets probably don’t even have a description body since what I ended up doing is just described in the commit message.
- kelnos 3y ago
  To me, the ticket id is extra info and goes at the end of the message body, not in the title at all. I've seen far too many people think that putting the ticket id into the commit message can be a replacement for writing a good commit message. I've even seen people think that "Fix #123" is all they need to put in there. The commit history should be the primary source of truth for what changes have happened. I've also been at orgs where they've switched from one ticket tracking software to another, and haven't maintained history, or even when they do, the ticket ids and up changing afterward.
cmgriffing 3y ago
I find commit messages are more useful when we consider machines to be primary the consumers of them. Using conventional commit style messages allow us to generate changelogs and modify our semver versions automatically. Generating changelogs by hand is extremely tedious. Modifying semver by hand leads to caring too much about the number. Like others have pointed out, the context and "why" can easily be tracked by linking out to the ticket/task that the work is associated with.
- avgcorrection 3y ago
  I love that (when) commit messages are for people first. I don’t want to read stilted and robotic commit messages just because someone wanted to shave off five minutes when creating whatever software artifact like a changelog.
teo_zero 3y ago
The rationale of subject-first is clear. But what about the other rules: correct instead of fix, rather than instead of rename... They seem pretty arbitrary to me.
- hmeh 3y ago
  Author here. I don't know that arbitrary is the right word. They were decided, and generally found to be superior to alternatives. We stick to them so as to avoid special variation (https://github.com/aaronjensen/software-development/blob/master/special-variation.md https://github.com/aaronjensen/software-development/blob/mas...). For example, correct reinforces the notion that things can be wrong, mistakes can be made, so we correct them. This is essential to our team culture. "Rather than" came from Eventide's norms and I wasn't there when it was discussed initially. It works for concepts other than renames, so it is more flexible, but I can't say that was the reason for the initial decision.
sbellware 3y ago
Some additional context on this: - There are additional organizational and process mechanics in-play that are out-of-scope for just a write-up on commit messages - The team is made up of around 15 people supporting around 400 repos and about 8 live products - The team DOES NOT use pull requests. Contributors are expected to be socially capable and fully engaged in the inter-personal, realtime communication that supports high-performance, low-handoff work. - The ticketing system is NOT the primary means of communication between team members. It's merely a catalog of work items with only high-level supporting notes. A work item, as the old saying goes, is a "placeholder for a conversation", rather than a work order that can be executed upon by a contributor operating in isolation. - The original author is describing an exceptional software product organization. He's not debating the merits of various subjective perspectives on what kind of personal flair might drive the content of commit messages. Instead, he's describing one small piece of a methodology that explicitly discourages personal flair and explicitly encourages (and provides supports for) direct communication, and rigorous attention to the team's well-considered, proven, and communicated norms. - Contributors on the team are expected to maintain their own work logs in the spirit of engineer's logs from engineering industries. If the "why" of a change is important, it will be recorded in the work log. Senior technical leaders (at a minimum) keep up with the individual work logs looking for hazards and maintaining an understanding of the learning that's taking place in the team. - Contributors on the team are expected to maintain equipment logs for the components that they're making changes to. This isn't the same thing as a SCM log, as an SCM log is for the SCM, not the product under development. - The reason that the "subject-first" approach is used is to get contributors to talk specifically to the impacts made to the software itself, rather than talk about themselves and their labors. It's about training developers (and designers, and operators, etc) to be more objective about the work they do, and to communicate it in an objective way. Mentions of "changed", "fixed", etc, are records from the perspective of the worker, not the product. When scanning the list of changes made to a work product, the team members are primarily interested in the impacts to that piece of equipment first and foremost. The work product change logs are voiced in terms of the work product, and not the worker. Again, the reflections, learning, questions, observations, etc, of the humans involved in the work go into the human's own logs, and are supported by the person-to-person processes that are beyond the scope of the article on commit messages. - These 15 people with their 400 repos and 8 live products was winning industry awards within a couple months of go-live within the first year of the team's charter. There's nothing average about the team, the product, and the methods in-play. The commit messages are just one detail of the finely-honed process and culture that were intentionally designed, socialized, and painstakingly-supported to achieve its objectives. - The author of the article is describing one facet of an overall product development system for a high-performance software organization. He's not trying to spark a dialog about the myriad opinions of how commit messages are written across the breadth of software development within processes and cultures that may not go much beyond the cross-referencing of items between ticketing systems with an SCM system, which is arguably a higher-ceremony approach from an artifacts perspective, but also a "bare minimum" from a process and culture perspective. It's not entirely pertinent, but just in case there's some question as to whether this work is being done in a business of some scale or other at some particular time or other in a business's lifecycle that accounts for how the development system works, and whether it's a special case: the business context of team's work is a $1B multi-national with about 2,000 employees working in the regulatory side of corporate law, finance, and venture capital. The business context isn't the enabling factor or the deciding factor. The product development system in-effect is the key factor, and it was shaped explicitly for its outcomes irrespective of the business context. The development system has been used at various companies up-and-down the axis of business scale and scope. The single greatest contributing factor of the team and its work is that they carry very little technical debt, and the methodology required to work this way touches every molecule of process, organization, and culture. It would not be recognizable from the perspective of typical mid-curve software development, and it would not be understood by examining any single process element in isolation.
jes5199 3y ago
commit messages are a code smell. If you need to commit code, then you’ve already made a mistake
alberth 3y ago
I go the other extreme and do below as commit messages. https://keepachangelog.com https://keepachangelog.com Makes creating change logs super easy & clear. Which is prefacing each commit with either: ADDED for new features. CHANGED for changes in existing functionality. DEPRECATED for soon-to-be removed features. REMOVED for now removed features. FIXED for any bug fixes. SECURITY in case of vulnerabilities.
- funcDropShadow 3y ago
  What do you do for refactorings?
  - alberth 3y ago
    CHANGED

151 points by s4i 3y ago

Meh, as in this doesn’t feel like it really matters. Like other commenters, there are exceptionally few situations when I find myself just reading the commit log, so the claimed psychological advantage appears moot in the context of the common/standard software development process (which is very much not what author’s team does, so I acknowledge this approach brings specific measurable advantages for them). When I do need to read the commit log, it’s typically for a third party component and I look for broad categories I need to pay attention to (security fix? Behaviour change?) — this aligns well with the conventional commits standard and well managed release notes. But, to not have to read commit logs, we also do the rest of the conventional software development workflow (PRs, team meetings, etc) that serves to build the awareness of what’s being done.

TacticalCoder 3y ago

I like to be able to read the commit line following the sentence: "This commit shall ...". For example from TFA: "Fix code example in the field_name method" gives: "This commit shall fix code example in the field_name method". OK, cool, I may or may not merge it, pull it, whatever-it. But I know what it'll do should I use it. Now from what TFA recommends: "Default reader batch size is 1000" Means nothing. Tells nothing. Is 1000 good or bad? No clue. Is it causing a bug? A performance issue? Was it 1000 before the commit or after applying it? Zero information. I'll pass and keep using the "best practice". Using the best practices the commit would read: "Change default reader batch size to 500" or "Change default reader batch size to 1000" or maybe "Add default reader batch size" (btw the commit line in TFA is so bad that I'm not sure at all it's 500 or 1000 or something else I should put here to make my point). The "best practices" aren't a bias. They're the result of people thinking long and hard as to how to make commit lines as clear as possible. I look at how multi-million lines codebase like Linux or Emacs are doing it and use that as the authority. If it works well enough for these projects, it works well enough for smaller projects.

hmeh 3y ago
> I like to be able to read the commit line following the sentence: "This commit shall ...". I'd guess there's a near zero chance you do this when looking at (scanning) a list of commits. This is a mnemonic for writing commit messages in the commonly accepted style. If you do that in order to help you understand a commit message every time you read one, that may be a personal thing. > Means nothing. Tells nothing. Is 1000 good or bad? No clue. Is it causing a bug? A performance issue? Was it 1000 before the commit or after applying it? Zero information. > Using the best practices the commit would read: > "Change default reader batch size to 500" or "Change default reader batch size to 1000" You realized you could ask the same questions about the versions you put forward, yes? Aside from the "Was it 1000 before the commit..." which, on our team, would be such a ridiculous question it wouldn't even enter the mind. As I said somewhere else, the headline for a celebrity dying does not ever read: "Some Celebrity Is Sick" > I'll pass and keep using the "best practice". Works for me :) > I look at how multi-million lines codebase like Linux or Emacs are doing it and use that as the authority. If it works well enough for these projects, it works well enough for smaller projects. Linux and Emacs have completely different circumstances than most software projects. The idea that cargo culting their practices is good for "smaller projects" is exactly why I wrote my article on best practices. By the way, I contribute to Emacs and I don't find their particular commit message format good or useful. It's particularly onerous, redundant, and does not tend to provide useful additional information (in particular the mandated change log portions -- people do often supply additional information, which can be useful). I tend to find the devel list and bug list more useful for the context of a change, which fits with our experience as well with work logs and project logs.

rco8786 3y ago

I think I would prefer this style. And also the discourse around commit messages and their various flavors may be one of the biggest wastes of time in terms of ROI in our industry. I’ve been doing this for 14-15 years and can probably count on two hands the number of times I’ve needed to look at historical commit messages.

naavis 3y ago
I don't know, I do it almost daily. So your mileage may vary.
- sverhagen 3y ago
  I do it almost daily too. What _is_ rare, is finding a commit message that tells me anything useful that I couldn't have derived from the diff also. I don't need your life story, but sometimes some context about why something was needed is great.
  - rco8786 3y ago
    Exactly. Im in git history all the time. But the messages themselves…eh. Im basically always looking for a change in a specific file or set of files, and then I just pull up the diffs.
  - madeofpalk 3y ago
    What I do find useful is the subject/area, and the author.
  - hmeh 3y ago
    Author here. Yes, the diff should tell you more, but you shouldn't need to look at the diff until you have an idea what the contents of that diff are about. It's like the links on the hacker news home page -- clicking them will always tell you more, but the index should be geared for the use case, which is scanning, typically.
    - sverhagen 3y ago

atoav 3y ago

Bottom line first. I like it.

henning 3y ago

Like everything in software development, this is just personal preference without any actual evidence, a substitute for actually making software with quantitative quality metrics that users actually care about. Let's fiddle with our commit messages, PR formats, code formatting, etc. etc. etc. instead of addressing the fact that our website has 6 different fonts and makes 30 HTTP requests to show a few hundred bytes of text.

idlephysicist 3y ago
I totally agree, I have seen people get so fixated on this in addition to: - review feedback format - variable naming - keeping line lengths to 80 lines - log message formats (sweet jesus the amount of time wasted debating that alone) Whenever I see these conventions about commit formatting they generally seem to focus on the first line (notable exceptions being Git and the Linux kernel among others I assume), one line is rarely enough to describe the change – I’m not advocating for writing an essay for a 5 line change though in some cases it might be warranted. Professionally I rarely see useful commit messages, by useful I mean something that could be read by someone without context and get a general understanding of why a change was made. Frequently I have seen “updates” / “wip” etc. in the master branch. More frequently I see that the quality of commit message decreases with an engineer’s seniority – though like every thing there are exceptions.
hmeh 3y ago
Author here. You're well within your rights to believe it is personal preference, but it's somewhat hard to refute the fact that it's easier to scan lists when you put the most significant (i.e., the part that varies the most) first. Imagine if every item on Amazon's list of products was of the format: "Product for purchase, Headphone, Sennheiser Momentum 4"

egnehots 3y ago

there are pros and cons to both verb-first and subject-first commit styles. verb-first commits can be organised in a few categories. since they are few commit verbs (fix, add, refact..), always use the same verb prefix for bug, features messages and you will have nice categories to scan/filter: - add feature - fix bug - refactor logic On the other hand, subject-first indeed put the important part first and let you search for a term: - Instance configure template method called from constructor - Store's project method is an alias for fetch - Title is changed Depending on the use case, are you often searching for something? or would you like to highligh the nb of bugs/features in the last release?, one style is better suited than the other. For important changes, I like the linux kernel style: oneline summary, details (problem, impact, solution..) https://docs.kernel.org/process/submitting-patches.html https://docs.kernel.org/process/submitting-patches.html

laerus 3y ago

After started using conventional commits [1] for my messages the style of Subject-First commit messages comes almost naturally. [1] https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/

Salgat 3y ago

In my experience consistency is more important than any specific style of commit messages. Similar to style guides for code; there's plenty of ways to approach it, but the real value is the consistency in how things are written across all developers.

tahnyall 3y ago

I prefer the first version, I didn't find the second version to be more "scannable" and it seems to me to be more esoteric requiring study to realize what was recorded. The first version is clear, each commit makes sense and is what I'd be grepping for when trying to find a commit.

knorker 3y ago

This seems super subjective, while being written as if it's not. I find this way WAY harder to read/scan, and very much prefer Google's standard: https://google.github.io/eng-practices/review/developer/cl-descriptions.html https://google.github.io/eng-practices/review/developer/cl-d...

davidmurdoch 3y ago
What is CL here?
- king_geedorah 3y ago
  CL stands for change list. https://google.github.io/eng-practices/ https://google.github.io/eng-practices/
- tuwtuwtuwtuw 3y ago
  Change List. Similar to pull request I think.
- tsimionescu 3y ago
  "Change List", Perforce's name for the rough equivalent of a commit. It's called a change list even though it's a single commit because Perforce tracks changes per file, so if you modify multiple files in a single commit, you are introducing a list of changes in their model.
- deleted 3y ago
  [deleted]
- deleted 3y ago
  [deleted]
- deleted 3y ago
  [deleted]
- knorker 3y ago
  Sorry, yeah I should have clarified that. For the purposes of the topic at hand, "CL" is "commit".

asylteltine 3y ago

This doesn’t work with conventional commits which is flat out awesome. But I will try mixing both because I like the idea

ikari_pl 3y ago

Error messages. Get to the meat of it in the first 3 words, there's a high chance that's the only part that will get read, or even displayed. It must be the most meaningful part of the error message.

twodave 3y ago

I look at commit messages every day. I actually don't love a message that just describes the code change (I can figure that out on my own if I look at it long enough). That's fine for bigger or more misleading changes, but when I'm looking at blame/history I'm usually very aware of what the code is doing already. My question at those times is less about "what" and more about "why". Why was this change made? Sometimes that can be found by looking at accompanying tests (if the original author was so gracious), but if it's not in the commit (or only obtusely so, as many developers I know tend to commit in what I'll call "stream-of-consciousness" style) then I've got to go outside the codebase to research by interviewing people (assuming they're still around and remember) or trawling through our project management system to try and line up released features/fixes with the change. It quickly becomes an inexact science. That said, in my experience, the larger an organization, the more commit messages get looked at. On my side projects where only 1-3 people are involved, commit messages only really show up on the PRs as things are going in. Sometimes we complete our own PRs to keep up the velocity since we're all working async part-time. Rarely if ever do we look back to figure out why we did something because the project is so small.

BoxFour 3y ago
> My question at those times is less about "what" and more about "why". Why was this change made? Isn't the essence of the commit message body to delve into the 'why'? The ability to swiftly glean the 'what' from the commit subject line aids in identifying the appropriate commit for review. The commit message body can then have a detailed explanation of the reasons behind the change.
- jbverschoor 3y ago
  The diff is the what. Putting what in the message is fluff to make gatekeepers happy
  - masklinn 3y ago
    Disagree. Putting "what" in the message can be fluff, in the same way repeating the code in a comment is fluff. But the broad strokes or considerations of the what may not be obvious from the diff. Expressing what the commit intends as prose can help with understanding, with discarding irrelevant change data, with post-mortem analysis, ...

andai 3y ago

Spent 5 minutes trying to figure out where field_name is in the second list... I thought it was the same commits rewritten to be more scannable, but they are from a different project. (I scanned, naturally, the article itself!) Or more generally, I thought the point of the article would be that the function / variable names from the first list would be moved to the beginning of sentences. But in the 2nd example they are completely absent, favoring much vaguer / high level descriptions. So we are unable to see the before/after effect for the same list of commits, I think most of the potential impact of the author's intended point is lost. (Also, the first half extolls the virtues of being able to read quickly, while the second half tells you to use longer sentences for everything for apparently no reason?)

hmeh 3y ago
Author here. I chose two real sets of commit messages rather than to fabricate one. Fabricating one may have made the second list easier to scan -- you'd already know what you were looking for and you would have some familiarity with the content. In any case, it's certainly not a perfect experiment or demonstration. The specific function/variable names do not often make appearances in our commit messages (though they do sometimes, as do class names). They do, however, make very clear appearances in diffs. Commit messages stand on their own for their own purpose -- it's an index, and indexes are for scanning. If you need to read further, you zoom in. Also, I wasn't trying to say to "use longer sentences for everything," where did you get that from? I offered some specific clarifications on how we write some common commit messages, and they may be longer than some alternatives, but our reasons are for clarity and consistency. We don't mind slightly longer commit messages, in large part because the first few words tend to be the most important.

r3trohack3r 3y ago

I personally prefer conventional commits. https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/ The subject line says what the purpose of the change is (CI/CD, tests, bug fix, new feauture), what component it primarily focuses on, and then a plain text one line summary. For example: ci(GitLab): Add rust build directory to cache This should improve build times by caching most of the compile tree between builds. In testing, I’ve observed builds drop from 2m to 30s when scheduled on a node with a primed cache. It also forces me to keep my commits focused. If I can’t create a one line summary of what I’ve done, it probably needs to be broken up into multiple commits.

ericrallen 3y ago
Conventional commits are great, especially if you add in commit linting. Being able to programmatically increment semantic versions and automatically generate relevant changelogs is awesome. It’s also nice to implement Commitizen[0] for a little hand holding until folks get used to the linting. I used to care a lot about doing things the way that felt right to me, but now I just want some common standard that is easy for everyone to follow, easy to automate, and easy to verify programmatically. Things like conventional commits and semantic versioning aren’t perfect, but they are quite good and apply broadly to many use cases with common tooling and conventions. -- [0]: http://commitizen.github.io/cz-cli/ http://commitizen.github.io/cz-cli/
diarrhea 3y ago
But they’re not mutually exclusive. The two concepts play well together!
rzzzt 3y ago
I find the word choice for types "feat" and "chore" infuriating for some reason. Feat?!
- SergeAx 3y ago
  "feat" is something that adds value to product's end users. The things we put on release notes. "chore" is something that adds value to the engineering team. The things we have to do to keep being productive.

isratjahan 3y ago

I like the first concept.

minimaul 3y ago

I like a style like: codebase section: short summary longer description if necessary eg: cocoaui: fix images being incorrectly aligned on high dpi displays We were calculating the position of the image in logical pixels, but not converting that to actual display pixels for rendering. I think it's a really nice style that makes commit messages really easy to scan in a short log, and lets you ignore commits easily that don't touch the area you're interested in

reactordev 3y ago

I’m against any style or enforcement of style of commit messages that breaks changelog I use git log history for changelogs with a little dressing for markdown. I could pull this from Jira but it’s worse. Stories aren’t changes. So I understand that some folks use git log for history and care about their code style so much as to enforce commit message stylecop, it’s overkill in my world and would only cause you to have to amend your commit or write a new message on squash.

gherkinnn 3y ago

The subject-first style felt grating at first, but comparing the two I found myself reading more per line than I did in the verb-first approach. Fix skip fix skip fix skip add skip I knew nothing at the end. The second style had me grasp more, as there were no obvious hooks to skip without knowing what had changed. But as others have said, commit messages are a cesspool of bikeshedding and ultimately useless, unless every commit is a self-contained chunk of work which it rarely is. On the side, I enjoyed all of this author's thoughts in the repo. Good find.

hmeh 3y ago
Author here. Thank you! I agree that there can be plenty of bike shedding about them, which is why we have an approach that is based on human psychology and can be backed up in that way. We don't often put too much more in the content of a commit message -- the diff, plus the repo it's in (we have many repos) tell you most what what you need to know. If you want more context, every team member has a daily work log that is available to the entire team, so you can see more about what they worked on and why in that work log.
- pseudalopex 3y ago
  > I agree that there can be plenty of bike shedding about them, which is why we have an approach that is based on human psychology and can be backed up in that way. You optimized for a micro benchmark and presented no data.
  - hmeh 3y ago
    It was a design decision, and like most design decisions, it was based on first principles and a-priori knowledge. If we had to base all of our design decisions on data and benchmarks, we wouldn’t be able to design anything. I can assure you, that if a better format with better properties came around, we would likely switch to it (assuming we accounted for switching cost and the variation we would be introducing).

vitus 3y ago

> The second style likely feels foreign, and possibly uncomfortable. It's passive voice and present tense — all the things that we aren't supposed to make our commit messages. Nitpick: it's passive voice and indicative mood (and sometimes subjunctive) -- there's nothing wrong with present tense. "Fix typo" is active voice, present tense, and imperative mood. (The Rails commits that dip into past tense bother me slightly, but whatever.) Broadly, I have a few opinions on commit messages. The style doesn't really matter as much to me, although I'm a relatively strong adherent to "one-line summary, followed by paragraph(s) of additional context" (as is standard in the Linux kernel, and supposed best practice at Google even if it isn't universal by a long shot). One is that the commit message should be useful for anchoring a search for potentially relevant changes, and for providing broader context re: why the change was made. At the same time, I waffle between putting more description in the commit message, versus just commenting the code (or making the code clearer). The last is more pragmatic: when I'm searching for a specific change, I'm often looking at the history of a particular file (blame or otherwise). I can quickly filter out all the "fix typo" messages or "[LSC]" (large-scale change, term used at Google for various company-wide code health refactors). Or if I'm trying to figure out which change introduced a bug, I'll probably bisect it one way or another (I often try to short-circuit that bisection toward the end to save the last few iterations). Either way, I don't actually spend that much time reading through commit messages until I've identified a potentially problematic change.

deleted 3y ago
[deleted]
n_plus_1_acc 3y ago
Around half of them are actually avtive voice, like "Snapshot interval build argument overrides ..."
hmeh 3y ago
Author here. Thank you, updated. We don't tend to put much in the commit messages themselves. The code often speaks for itself (and if it doesn't, it isn't likely that the author would have had much more to say about it at the time, as our norm is to comment "why" when necessary). We also have work logs we can refer to that sometimes have the why, or at least some of the context for the work we are better trying to understand.

graypegg 3y ago

Past commit messages have 2 uses to me. - Blame view, where I usually want to know the ticket number so I can track down a story which has the business rules the dev was implementing. - Bisect, where I want to know if this works or not without having to do a test run every time. This format is alright I guess, but the best thing you can do honestly is just TICKET: [done/works but wip/does not work] [describe what you’re thinking] AB-1234: does not work, trying to rewrite this controller to remove all the duplication, /api removed temporarily To me, that doesn’t have to be set in stone. No one likes working with a commit message stickler when standardized formats are only useful ~20 times a year to save 10 minutes each. (In my experience)

vlovich123 3y ago

The problem with the experiment is that when I’m scanning, typically I’m never scanning and then getting tested on the contents after the fact. It actually took me longer to spot any mention of store in the second example after being told what I was looking for than it did for me to find field_name after being told to look for it. YMMV.

gavinhoward 3y ago

Strong disagree. Commits are actions and should place actions first. If you need to find a specific item, that is what `git log --grep` is for.

hmeh 3y ago
Author here. Commits aren't actions -- they are a log of an action being taken. You, the committer, are committing. What you commit, goes into a commit log. We choose to make our commit messages describe the change, rather than the person that made the change. It's about the work, not the worker.
- gavinhoward 3y ago
  And the work does an action on the code.
  - hmeh 3y ago
    I'm trying to imagine my commits coming alive and doing things to my code. I think you may be taking the "When this commit is merged..." thing a bit far, as commits don't actually do anything. They just are. We don't tend to do ourselves any services by anthropomorphizing aspects of our work. I'm happy to concede that we see things very differently.
    - avgcorrection 3y ago
      It has nothing to do with anthropomorphizing. The Git project uses the style of: Refactor x As in: command (verb: refactor) the code to change in this way. That a person wrote the code is irrelevant.
      - hmeh 3y ago
        I was responding to the author of the comment I was responding to, who was anthropomorphizing the commit itself claiming that it did something. I agree that the person who write the code is irrelevant, though I realize that in a different way. I also recognize that it varies from Git/Linux/etc. We do it for usability and other reasons and one only needs to look at git itself to recognize that the original authors did not have usability in mind when designing it. What they built is incredibly powerful, but it's rare for usability and technical prowess to overlap.

deleted 3y ago

[deleted]

turtleyacht 3y ago

Verb-first is already the subject. We fill in the latter portion of a sentence that begins (in our head), "When merged, this commit will..."

IshKebab 3y ago

I prefer the first style. It reads way less weirdly. I spend way more time reading commit messages than "manually searching" by scanning them. I either arrive at the commit from git blame, or I use this really cool feature of computers called "ctrl-F".

Groxx 3y ago

Ehhh... maybe. One implicit trade-off here is how low detail the second set is, and that'll happen any time you force a structure - mandated structure takes more space on average, sometimes significantly more. Passive voice wastes a lot of space too (in English anyway). Personally I think this is better solved by a changelog doc (which you can wordsmith for outsiders, which is an entirely different target than internal developers) and `git blame` (I never browse all of history to find changes to a method, just blame it for the latest or `git log -p -L` to check a series of changes to a file/func/etc).

hn_throwaway_99 3y ago

TBH, at least at every company I've worked at recently, the style of the commits is more or less irrelevant to me save for one very important piece: The commit starts with the ID of the ticket for the code change (or some placeholder for very small commits where a ticket wasn't necessary, e.g. [no-tix]). The biggest benefit of this is that these commits can then be automatically linked to the ticket which often has a lot more detail and conversation. 99% of the time when I'm looking at commit history, I'm not just generically scanning. I'm usually looking for a particular change, or when something touched a particular file, etc. Even the example given in the linked page isn't really relevant to me, because I'm rarely "quickly scanning" a whole commit log for something in particular - I'd always just use a search feature (in GitHub or some git IDE plugin) for that.

avgcorrection 3y ago
I agree that the ticket id should go somewhere in the commit message. Certainly if things like pull requests are tied to tickets. However I get a little concerned that such sentiments are so popular here. Because the ticket id is a nice contextual link. But the commit message should be self-contained with regards to the change.[1] It’s a version control system. That includes an explanation as well. The explanation for each revision is integral. And I don’t think people here really disagree with that. Just that they might prefer to put all that integral information somewhere else—the information (princess) is in another castle, Mario. Why? Why not at least just copy-paste the relevant information into the version control system proper? I see this all the time; people often do the same with GitHub pull requests—paragraphs upon paragraphs in the pull request description and then just a “Merge <convoluted URL>” in the merge commit message! It’s not that I blame people for this. Maybe Git is just so unergonomic that many would prefer to offload everything into another interface (even Jira). [1] My tickets will usually have all the history. Maybe a lot of back and forth. The commit message though will just have what was done when all was said and done—no back and forth, just the result. And some of my tickets probably don’t even have a description body since what I ended up doing is just described in the commit message.
kelnos 3y ago
To me, the ticket id is extra info and goes at the end of the message body, not in the title at all. I've seen far too many people think that putting the ticket id into the commit message can be a replacement for writing a good commit message. I've even seen people think that "Fix #123" is all they need to put in there. The commit history should be the primary source of truth for what changes have happened. I've also been at orgs where they've switched from one ticket tracking software to another, and haven't maintained history, or even when they do, the ticket ids and up changing afterward.

cmgriffing 3y ago

I find commit messages are more useful when we consider machines to be primary the consumers of them. Using conventional commit style messages allow us to generate changelogs and modify our semver versions automatically. Generating changelogs by hand is extremely tedious. Modifying semver by hand leads to caring too much about the number. Like others have pointed out, the context and "why" can easily be tracked by linking out to the ticket/task that the work is associated with.

avgcorrection 3y ago
I love that (when) commit messages are for people first. I don’t want to read stilted and robotic commit messages just because someone wanted to shave off five minutes when creating whatever software artifact like a changelog.

teo_zero 3y ago

The rationale of subject-first is clear. But what about the other rules: correct instead of fix, rather than instead of rename... They seem pretty arbitrary to me.

hmeh 3y ago
Author here. I don't know that arbitrary is the right word. They were decided, and generally found to be superior to alternatives. We stick to them so as to avoid special variation (https://github.com/aaronjensen/software-development/blob/master/special-variation.md https://github.com/aaronjensen/software-development/blob/mas...). For example, correct reinforces the notion that things can be wrong, mistakes can be made, so we correct them. This is essential to our team culture. "Rather than" came from Eventide's norms and I wasn't there when it was discussed initially. It works for concepts other than renames, so it is more flexible, but I can't say that was the reason for the initial decision.

sbellware 3y ago

Some additional context on this: - There are additional organizational and process mechanics in-play that are out-of-scope for just a write-up on commit messages - The team is made up of around 15 people supporting around 400 repos and about 8 live products - The team DOES NOT use pull requests. Contributors are expected to be socially capable and fully engaged in the inter-personal, realtime communication that supports high-performance, low-handoff work. - The ticketing system is NOT the primary means of communication between team members. It's merely a catalog of work items with only high-level supporting notes. A work item, as the old saying goes, is a "placeholder for a conversation", rather than a work order that can be executed upon by a contributor operating in isolation. - The original author is describing an exceptional software product organization. He's not debating the merits of various subjective perspectives on what kind of personal flair might drive the content of commit messages. Instead, he's describing one small piece of a methodology that explicitly discourages personal flair and explicitly encourages (and provides supports for) direct communication, and rigorous attention to the team's well-considered, proven, and communicated norms. - Contributors on the team are expected to maintain their own work logs in the spirit of engineer's logs from engineering industries. If the "why" of a change is important, it will be recorded in the work log. Senior technical leaders (at a minimum) keep up with the individual work logs looking for hazards and maintaining an understanding of the learning that's taking place in the team. - Contributors on the team are expected to maintain equipment logs for the components that they're making changes to. This isn't the same thing as a SCM log, as an SCM log is for the SCM, not the product under development. - The reason that the "subject-first" approach is used is to get contributors to talk specifically to the impacts made to the software itself, rather than talk about themselves and their labors. It's about training developers (and designers, and operators, etc) to be more objective about the work they do, and to communicate it in an objective way. Mentions of "changed", "fixed", etc, are records from the perspective of the worker, not the product. When scanning the list of changes made to a work product, the team members are primarily interested in the impacts to that piece of equipment first and foremost. The work product change logs are voiced in terms of the work product, and not the worker. Again, the reflections, learning, questions, observations, etc, of the humans involved in the work go into the human's own logs, and are supported by the person-to-person processes that are beyond the scope of the article on commit messages. - These 15 people with their 400 repos and 8 live products was winning industry awards within a couple months of go-live within the first year of the team's charter. There's nothing average about the team, the product, and the methods in-play. The commit messages are just one detail of the finely-honed process and culture that were intentionally designed, socialized, and painstakingly-supported to achieve its objectives. - The author of the article is describing one facet of an overall product development system for a high-performance software organization. He's not trying to spark a dialog about the myriad opinions of how commit messages are written across the breadth of software development within processes and cultures that may not go much beyond the cross-referencing of items between ticketing systems with an SCM system, which is arguably a higher-ceremony approach from an artifacts perspective, but also a "bare minimum" from a process and culture perspective. It's not entirely pertinent, but just in case there's some question as to whether this work is being done in a business of some scale or other at some particular time or other in a business's lifecycle that accounts for how the development system works, and whether it's a special case: the business context of team's work is a $1B multi-national with about 2,000 employees working in the regulatory side of corporate law, finance, and venture capital. The business context isn't the enabling factor or the deciding factor. The product development system in-effect is the key factor, and it was shaped explicitly for its outcomes irrespective of the business context. The development system has been used at various companies up-and-down the axis of business scale and scope. The single greatest contributing factor of the team and its work is that they carry very little technical debt, and the methodology required to work this way touches every molecule of process, organization, and culture. It would not be recognizable from the perspective of typical mid-curve software development, and it would not be understood by examining any single process element in isolation.

jes5199 3y ago

commit messages are a code smell. If you need to commit code, then you’ve already made a mistake

alberth 3y ago

I go the other extreme and do below as commit messages. https://keepachangelog.com https://keepachangelog.com Makes creating change logs super easy & clear. Which is prefacing each commit with either: ADDED for new features. CHANGED for changes in existing functionality. DEPRECATED for soon-to-be removed features. REMOVED for now removed features. FIXED for any bug fixes. SECURITY in case of vulnerabilities.

funcDropShadow 3y ago
What do you do for refactorings?
- alberth 3y ago
  CHANGED