How to make commits, so that later it does not hurt

A few days ago, David Demaree, Typekit’s chief Adobe contributor, published a cool git book for people . In order to draw attention to her, he published a squeeze of the most interesting, in my opinion, chapter on how to arrange commits so that the wolves were whole, the sheep were full, and the fox did not come. And for this weekend I prepared a squeeze from a squeeze - a shortened and adapted translation so that you can quickly read and add the most valuable things to your experience.

Commit Art

A comment to a commit is probably the most important part of it, since this is the only place where not only what has been written is written, but why .

- from comments

A good comment on a commit is short. And not only because brevity is a sister. The messages to commits are most often read in the change log, where there will be a lot of them . Consider each message as a news headline on the Internet: it should be short enough so that you can quickly flip through the news and contain just enough information so that you can find important information for you. If you have more than a couple of programmers in the team, then the commit log allows you to be aware of what is happening in the project. Git does not impose restrictions on the length of the message; after a brief announcement, you can add several paragraphs of text:
')

Updated Ruby on Rails version because security Bumped Rails version to 3.2.11 to fix JSON security bug. See also http://weblog.rubyonrails.org/2013/1/8/Rails-3-2-11-3-1-10-3-0-19-and-2-3-15-have-been-released/ 

Please note that the entire message contains quite a lot of information, and the first line contains a short squeeze. Because in the log you will see only the first line:

 commit f0c8f185e677026f0832a9c13ab72322773ad9cf Author: David Demaree Date: Sat Jan 3 15:49:03 2013 -0500 Updated Ruby on Rails version because security 

Your favorite text editor

git integrates with both console editors (vim, emacs) and graphic (Atom, Sublime, TextMate). Invoked without --message git will transfer the text stub to the configured editor. After editing the message, it is enough to save the open file and close the editor, git will determine that the message has been changed and uses it. An example of git integration with Atom:

 $: git config --global core.editor "atom --wait" 

Each editor needs its own command line keys, and in GitHub help you can find a good overview of how to customize popular text editors.

Comment to commit

When you write a comment to a commit, I recommend sticking to the following rules:

• Carry favor
  
  Remember that the purpose of a comment is to let your colleagues understand what is happening in the project. Put yourself in the reader's place and think how best to describe why this commit was made.
  
  
• Beware of fraud
  
  Often we want to write "stupid bugs" or "fixed the problem." Do not succumb to this weakness, try as clearly and clearly asks what was done and why.
  
  
• Link information
  
  If a commit is related to some external information - a bug report, an article on a wiki, or something else, then it’s a very good idea to explicitly indicate this in the comment to the commit,
  like so

   Replace jQuery onReady listener with plain JS; fixes #1357 

  Many bug trackers (including the one built in github) integrate with git and automatically mark bugs as fixed if they see the bug number along with a reserved word such as fixes in this example.
  
  
• Be (enough) detailed
  
  Do not write what has changed - it is always visible on the defa. Write why changes were made. This is exactly what is not visible on the defa. Try to fit the first line of 70 characters - you can always write additional information in a separate paragraph after the empty line.
  
  
• Be consistent
  
  So that your change log is read as a single news feed - take some time to explain to the team how best to write comments for commits. It’s a good idea to create a page in your wiki (do you have an internal wiki?) With examples of good and bad comments.
  
  
• Use verbs
  
  Often there is a temptation to write a comment to the commit of the “correction” type. But remember that the change log is the history of your actions on the project, and the actions are best described with verbs. If this is not done, it is very easy to degrade to such
  comments

   # Making the last homepage update before releasing the new site $: git commit -m "Version 1.0" # Ten minutes later, after discovering a typo in your CSS $: git commit -m "Version 1.0 (really)" # Forty minutes later, after discovering another typo $: git commit -m "Version 1.0 (oh FFS)" 

  In addition, this is a very simple rule that is easy to follow: “I just changed the code. What and why did I do? ”,
  eg

   $: git commit -m "Update homepage for launch" $: git commit -m "Fix typo in screen.scss" $: git commit -m "Fix misspelled name on about page" 

Your comments?

I hope this translation will be useful to many habratchiteli. As a developer, I share the opinion of the author and will be happy to discuss in the comments the difficult question of creating a readable commit log.