Friday, March 26, 2010

On commit messages

I would like to address the issue of commit messages. Good commit messages can make finding bugs and understanding the timeline of a project easy, and bad ones can result in an infuriating waste of time reading diffs and trying to locate information.

First of all, all commits should be atomic, that is they shouldn't include unrelated changes. Fixing a typo or spacing while fixing bug in related code is acceptable, but fixing 6 bugs and adding 2 features in the same commit makes it hard for people to parse out what change was for in the future. A good rule of thumb is that if a summary of your changes can't fit in one line, it's probably too big.

The first line of the commit message is most important part. This is especially true today, where many DVCSes only show the first line of the commit by default in their log command. The summary line should succinctly summarize what your change is and what it accomplishes. It need not be a full sentence, but just a bug number or general statement ("fix this") is not appropriate. The best summary lines quickly inform any log browser of the purpose and changes in the commit. Summary lines should also never be wrapped. Nothing is more annoying than reading a summary line which is cut off in the middle by a line break. Simple typo fixes do not require complicated messages. Good examples:
fix #2345 by preventing add() from accepting strings

fix a segfault in foo_my_bars() #4563

fix spelling

add a Python interface to the tokenizer #3222

and bad ones:
test and a fix



a huge change to Foo class

why does this not work?

bug #4543

After the summary line can optionally come a body. A blank line should always separate the commit message from the body and different sections of the body from another. Bodies should also always be line wrapped. The body can include any of the following:

  • Bullet points describing various aspect of the change in more detail.

  • A paragraph description explaining why how something was implemented or why it's written a certain way.

  • A reference to mailing list discussions or decisions that lead to the commit.

  • Authors and attributions.

  • Any other significant information about the commit. For example, explain how it affects external components or might result in unexpected behavior.

Some projects follow the convention of listing affected files in bullet points and describing the individual changes to each. I personally find a prose summary of the changes in the body along with a diff or the verbose version of the log which shows changed files more helpful than this technique.
Good examples of complete commit messages:

normalize encoding before opening file #3242

This change requires that tokenizer.c be linked with the Unicode

silence foo warnings by default

Approved by BDFL in

support unicode in shlex module #4523

This is implemented by providing a separate class for Unicode and
requiring a locale to be set before parsing commences.

Patch by J. Hacker and J. Programmer

boost the speed of keyword argument comparisons

This improves some function calls by over 30% by comparing for
identity before falling back to the regular comparison. stringobject.c
was modified to provide faster access to a string's value.


Anonymous said...

Thanks for posting this. It's good for novice as well as experienced programmers to review basics from time to time.

The unfortunate thing is that the people that most need to read and heed this never will.

Anonymous said...

It might also be helpful to point out that the "one line" should not be over five hundred characters long...

Not that I'm bitter or anything.

rajani said...

Thank you so much. It is a great article for me.
Django Online Courses
Django Training in Hyderabad
Python Django Online Training
Python Django Training in Hyderabad

sasi said...

This is a good post. This post give truly quality information. I’m definitely going to look into it. Really very useful tips are provided here. thank you so much. Keep up the good works.

Python Training in Chennai

Nick569 said...

Great post! I am actually getting ready to across this information, It’s very helpful for this blog. Also great with all of the valuable information you have Keep up the good work you are doing well.
CRS Info Solutions Salesforce Training   

Bindhu Lata said...

Nice post I have been searching for a useful post like this on salesforce course details, it is highly helpful for me and I have a great experience with this   
Salesforce Training India 

Vennala said...

I am so happy to found your blog post because it's really very informative. Please keep writing this kind of blogs and I regularly visit this blog. Have a look at my services.  
This is really the best Top 20 Salesforce CRM Admin Development Interview Questions highly helpful. I have found these Scenario based Salesforce developers interview questions and answers very helpful to attempt job interviews. Wow, i got this scenario based Salesforce interview questions highly helpful.

Aadhya said...

Myself so glad to establish your blog entry since it's actually quite instructive. If it's not too much trouble continue composing this sort of web journals and I normally visit this blog. Examine my administrations.  
Read these Salesforce Admin Certification Topics which are really helpful. I read these Salesforce Admin and Developer Certification Dumps and very much useful for me. I recommend this Salesforce Developer Training and Certification Course for you.

Keerthana said...

Thanks for your Ideas.Amazing Hints and Tips are sharing here about Python Training. Visit Once
python training in chennai | python training in annanagar | python training in omr | python training in porur | python training in tambaram | python training in velachery

Anitha said...

This article is really helpful for me. I am regular visitor to this blog. Share such kind of article more in future. Personally i like this article a lot and you can have a look at my services also: I was seriously search for a Salesforce training institutes in ameerpet which offer job assistance and Salesforce training institutes in Hyderabad who are providing certification material. It's worth to join Salesforce training institutes in India because of their real time projects material and 24x7 support from customer desk. You can easily find the best Salesforce training institutes in kukatpally kphb which are also a part of Pega training institutes in hyderabad. This is amazing to join Data science training institutes in ameerpet who are quire popular with Selenium training institutes in ameerpet and trending coureses like Java training institutes in ameerpet and data science related programming coures python training institutes in ameerpet If you want HCM course then this workday training institutes in ameerpet is best for you to get job on workday.

Python said...

Thanks for sharing all the information with us all.
Data Science Online Training
Python Online Training

Snehal Harshe said...

Thank you so much for sharing all this wonderful information !!!! It is so appreciated!! You have good humor in your blogs. So much helpful and easy to read!
Python Training in Pune

3RI Technologies said...

Thanks for sharing the informative content, very helpful and eye-catchy content. Thanks for sharing. Python Training in Pune

rebeca said...

great post ! This was actually what i was looking for and i am glad to came here!
PingFederate Training
MuleSoft Training

dmProITacademy said...

I recently came across your article and have been reading along. I want to express my admiration of your writing skill and ability to make readers read from the beginning to the end.
Python Classes in Pune

rao77 said...

Nice to see this BLOG..keep updating More infromation Digital Lync offers one of the best Full Stack training in Hyderabad with a comprehensive course curriculum with Continuous Integration, Delivery, and Testing. Elevate your practical knowledge with quizzes, assignments, Competitions, and Hackathons to give a boost to your confidence with our hands-on Full Stack Training.
DevOps Training Institute
Python Training Institute
AWS Training Institute
Online Full Stack Developer Course Hyderabad
Python Course Hyderabad
Online AWS Training Course Hyderabad
devops training in hyderabad
angular training in hyderabad

Anonymous said...

Thanks for sharing I really appreciate your knowledge

James said...

Thankful for sharing this post, It was vast looking at this article. I ought to research python course
keep in touch and stay related and guide us more.

kumar said...

This post is so helpfull and attractive.keep updating with more information...
Career In Data Science
Demand For Data Scientist

traininginstitute said...

I truly like you're composing style, incredible data, thankyou for posting.
data science course

Tech Engineer BD said...

Thanks for the great content Sir, I wil also share with my friends & onece again thanks a lot.
Seo optimization (Seo Ready) Best Responsive Blogger Template FlatMag
how to increase blog traffic fast
remove realme c3 frp bypass 2021
How To optimize Twitter Meta Tags in Blogger Update -2021

Hussey said...

Really nice blog. thanks for sharing
python training centre in chennai
best python institute in chennai

David Fincher said...

This post is so interactive and informative.keep update more information...
DevOps course in Tambaram
DevOps Training in Chennai

eMexo Technologies said...

Pretty Post! Thank you so much for sharing this good content, it was so nice to read and useful to improve my knowledge as an updated one, keep blogging.

Python Certification Training in Electronic City

Sarvesh said...

Gain great knowledge of IT for a better future. Get AWS Training in Chennai, the best software training institute from Infycle Technologies. Amazing software training institute and Placement centre in Chennai. And afford courses like Oracle, Java, Data Science, Big data, Python, Manual and Automation Testing, DevOps, Medical Coding, Power BI, Digital Marketing, Data Science, etc. With the excellence of training from best trainers for freshers, experience, and Tech professionals of any field. After the completion of the course, the student will be able to crack interviews from top MNC’s. For further enquiry approach us through 7504633633 / 7502633633 and get a free demo class.

Video Downloader said...

Awesome Post. Thanks For This Article

Matt Reeves said...

Great post. Thanks for sharing such a useful blog.
Artificial Intelligence Course in Velachery
Artificial Intelligence Course in Chennai