Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Every commit should combine:

- The code change itself

- Tests that demonstrate that the change works as expected

- Updated documentation relevant to that change (documentation should live in the same repo as the code to support this)

- A link to the ticket/issue that discusses the change

If you use a code review system such as GitHub pull requests or Phabricator you can enforce this kind of commit culturally - in your review point out that the test is missing or the documentation hasn't been updated or there's no link to an issue.

I like building pull requests up from several commits and then using the "Squash and merge" option to merge them into a single commit to master that includes all of the above.

Doing this is great for institutional knowledge, because "git blame" can always lead you to a comprehensive explanation of the change, including a link to the underlying ticket where the change was originally requested and discussed.



I agree that this can be a reasonable requirement for a completely new feature or a large change in behaviour. However, I'd say that enforcing this for all commits is a safe way to ensure that no one spends any effort on improving readability and robustness of existing code. It's one thing to quickly fix a typo or add a null check in code and send it for a quick review. A whole other thing to create a ticket, add a clear explanation on why this is needed, add a test for a weird edge case that shouldn't really occur and possibly make an documentation update for the edge case.

I'm more inclined than most of my team to do cleanup commits, but even I sometimes avoid them just for the extra cost of the regular review process.

I think a better approach is to have a culture that encourages making context dependent judgement calls, which is also what I try to do.

If it's something trivial like fixing a typo, I ask that this is made clear in the title, so investigators of an issue know that this CL is unlikely to be relevant.

If it's a minor change in behaviour, I ask for a commit message, and/or a comment in code, with a motivation of why it's needed.

If it's a bigger change in behaviour I want an issue linked to it, to make tracking easier in case there's followups needed or there's some regression due to this.

All this is of course based, not on some platonic ideal of what makes for good documentation, but rather on real experience of tracking down issues and adding features.

I know how annoying it can be to track down the commit of some functionality that looks really odd, only to find an empty message without even a reference to the issue that was being solved. But I also don't have this problem with commits that are clearly labeled "Fixed typo in X", those I can simply ignore.


I agree. Typos fixes and cleanups don't need this. The code + tests + documentation + issue link format should be for actual changes, not minor cleanups.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: