Hacker News Reader

Comment by stared | Hacker News Reader

Dots, periods or starting with caps - it makes no difference (except for aesthetics, perhaps.) What does (or at least: did for me) is Angular-style commit messages: https://github.com/angular/angular.js/blob/master/CONTRIBUTI....

> <type>(<scope>): <subject>

> [...]

> feat: A new feature

> fix: A bug fix

> docs: Documentation only changes

> style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

> refactor: A code change that neither fixes a bug or adds a feature

> perf: A code change that improves performance

> test: Adding missing tests

> chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

There is a big difference in knowing if someone added a feature, fixed something, or did some refactoring.

View on HN

Whenever I see a convention like this, I think to myself, “There is another data model being serialized into text.”

So very true. And I struggle with this. "Why should I write something out when tools could do it for me? Isn't me specifying it, then, just me being overly verbose?" But tools often don't - and may never.

I'm curious:

In any tool for any revision control system ever: in a list of commits, are the commit messages augmented with something useful beyond the basics? ("Basics" being e.g. the first 'n' characters of the human-provided commit message, a revision identifier, a timestamp, and a username.)

that tool would have to be quite specialized though and needs to enforce test driven development... how else could it check different benchmarks?

I can vaguely remember that PVCS had a way of explicitly linking tickets to commits, TFS probably has this as well.

Github has a way of linking issues with commits. You just mention the issue in the commit e.g. 'This commit closes #1' and i believe the issue will close with that as well, but it will show up in the issue.

Jira and other ticketing systems can often read repos and look for ticket ids. In my commits at work I just mention PRJCTNAME-142 and that'll link to a ticket and aggregate in jira all the commits/pull requeusts/branches... tagged with that

Our internal system has some integration between Jira and Github, such that if you comment a commit with the ticket number then you can see them all in the Jira ticket.

RTC works like that. You can also set up rules so that you can't even check in without linking a ticket.

Not exactly. The actual commit content is in the code difference. Code message is just some kind of human-readable abstract, or at least - a hit of what was changed.

There is a big deal of subjectivity (e.g. what is a bug, and what is a feature) but (as with any comments in the code) it is nice to see at least what was intended (e.g. someone wanted to position a misaligned button, or added it, or improved its visuals or optimized its click from O(n!) to O(1), ...).

The code message is metadata, like the commit hash, date and author. It could easily be split up into different fields.

> what is a bug, and what is a feature)

Well, for starters I wouldn't have a commit message stating that I just added a bug, though I might have one stating that I added a feature. :P

Great observation, though it's not a bad thing, necessarily (assuming you were even implying that it was).

In fact, it could be a very good thing, especially if the alternative is, eg, dropdowns for type and scope, and a separate popup for editing or adding new ones, and so on.

Having the data model loosely encoded as text, and understood only by convention among humans, who can then improvise changes to that model in exceptional cases, relying on other humans to make sense of those changes even though they are "outside" the agreed-upon model, is sometimes exactly what you want.

Also, as UI for input, text is often the fastest and most efficient -- again, just what you want. Of course, you could always do string validation on the text input to enforce your model, so this can be considered an orthogonal point.

And these considerations don't even touch upon the increased complexity and maintenance costs that your tool itself (in this case, git) will incur if it takes on the burden of maintaining the data model explicitly.

I agree.

The UX exists for the reader, the data model for the programmer. Sometimes, text is the best UX. For example, I love Markdown, a classic example of a data model serialized as text. I do not want a “rich editor” that speaks the data model directly.

I just see that as friction. Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard". Empower the developer and reduce friction to a minimum is my modus operandi.

Plus commit often and plan commits: with the example above the commit messages themselves are becoming a chore. Just make the message meaningful and link it to a JIRA issue or something. That's simple enough for me.

> I just see that as friction. Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard". Empower the developer and reduce friction to a minimum is my modus operandi.

Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.

>Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.

Which again may result in that refactoring never getting done. Many times I've found myself saying to myself "I must refactor this class.. But I'll just finish implementing this feature first so that I can get a clean commit with only the refactoring afterwards". Suddenly it's 5 o'clock and tomorrow I've forgotten about the refactoring need.

I struggle to see how this adds so much more effort?

You already know you want to refactor it so its not about forgetting to do it, and once the feature is done you'll probably have a better idea of how to refactor everything better and faster. It should actually save time in code productivity vs the extra minutes to do another commit.

I can't imagine my workflow being all that special, but I never have to deal with this?

I just write new features, refactor if needed, fix unrelated bugs, etc. When I feel like it's commit-time, I cherry-pick changed chunks or lines to commit into single coherent commits. If I've introduced a new feature that required refactoring, I'll first pick all the chunks that belong to the refactoring and commit; then I'll commit the new feature and afterwards commit any bugfixes and other side endeavors that may have come up during the development of the new feature.

This is one of the reasons I don't like working with Subversion anymore. Committing, say, two changed lines in a file with many changes is nearly impossible. In 'git gui' it's a simple as selecting the lines, right-click, "Stage lines for commit" and pressing the commit button, and I'm back to working on whatever it was I was really working on.

I tend to do this but with git add -p

I did this too in the past, but I've since found the convenience of 'git gui' too hard to ignore. The fact that it seamlessly runs on remote servers over X forwarding without having to install anything on the remote server really helps.

I find this method to not work too well for me because oftentimes features will have changes to the refactored code.

So I'm stuck with undoing my feature code or leaving smells of my feature in the refactored code.

Maybe I'm doing something wrong though.

> Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard".

Having maintained a few projects on Github, I routinely reject commits that both introduce new features and fix/refactor things. Refactoring is good, but jumping on a project and changing everything at once is a strong indicator of a lack of focus. The "fix some of everything" commits usually lack tests and documentation updates which wouldn't have been overlooked if the contributor took a step away and looked at the big picture.

Adding a new feature is the main reason you'd want to refactor something. Refactoring for its own sake is nice in theory, but ain't nobody got time for that. If you are doing real refactoring in a practical setting, it's probably a situation like adding a feature that closely parallels an existing one and now some of the stuff the old feature does can be factored out.

Refactoring is often done in order to implement a new feature, but that doesn't mean they need to be done in the same commit. A common workflow is to be implementing something, realize a refactor is needed, "git stash", refactor, commit, "git stash pop", continue feature work.

I'm a fan of creating two commits in that case:

- Refactor to prepare for Feature X - Implement Feature X

Note that these can be written in parallel, but just submitted as two separate commits (guess which side of the history editing debate I come down on :) )

Yeah, that's why I really hate rules like "all commits must have a user story attached". I'm not going to make a jira story for "function is poorly named", so if that's the rule then the code will fall to entropy.

For some reason the fact that "feature" is abbreviated to "feat" while "refactor" which is actually longer than "feature" is left alone irritates me - which, of course, doesn't mean anything other than to demonstrate how silly this kind of argument can be!

True, but "ref" is ambiguous since that abbreviation is usually used to mean "reference". "refac" or "refact" just don't roll off the tongue.

Every newspaper -- even ones that mostly use AP style -- has its own slightly different style guide. I don't think that proves style guides are pointless.

Hep, that's very good. I'm trying to do this recently, it is very hard btw unless you organize different topics beforehand, but then it is easy to escape since I often try to do something like "Submodule: ...." because later to merge just a single feature is simpler because commits are "tagged" with the name of the feature or module.

I do have problems with "(<scope>)", but I don't treat commit messages as statements defining code structure, but as hints of what I did.

(In any case, I don't use Angular-style commits for all projects. But learning about them was a small (but important) step in reducing complexity, vide http://www.johndcook.com/blog/2015/06/18/most-important-skil...)

One really nice side-effect is that these commits can be used to autogenerate changelogs, which is what the Angular team does.

Starting with caps or not makes a huge difference. It can easily break naive grep/awk. Other problems are typos and idiosyncratic spellings. Always spell-check your commit messages, it should be part of your git hooks.

By that logic we should also take into account all the other 1000s pieces of technology that can operate with text. In the end it all comes down to personal preference or the project guidelines.

> we should also take into account all the other 1000s pieces of technology that can operate with text

Yes, it called the Unix philosophy, good programs do it.

Reply on news.ycombinator.com