Software commit guidelines and tips

Having and following good commit guidelines is critical to ensure you're not doing cowboy coding. Here are my guidelines. I will update them as time goes. Feel free to comment.

General goals

Overall goal: quality quality quality. Every single of my revisions should be deployable. More details:

• a change should introduce as few new issues as possible
• a change should be easy to review (now and in the future)
• a change should have the least negative impact on the project.
• reverting a change should be as least painful as possible.

Things to ask yourself

• make sure you update your local code before you commit
• check that you are committing on the right branch
• if your development process allows it, have you published your patch for review
• don't break the build. Did you run your tests ?
• does the change come with a unit test ? Why not ? If you don't know how to write one, get some help.
• does the change come with a documentation update ? Why not ? Think about things you can add, change or remove.
  Also think about the various documentation levels: local to the code, javadoc at the method, class, package level, or some more high level documentation.
• commit your changes as single logical changes:
  • don't hesitate to make several checkins related to the same feature, as long as they are grouped logically (not physically). I.e. try to make small code increments. They make the code reviewing easier
  • try to group documentation changes with code changes in a single commit.
  • don't put unrelated changes in the same commit. E.g. a code cleanup and a new feature shouldn't be committed together.
  • if your change is related to several modules/projects, try to group the changes in the same commit. If not, try to make the commit so that the build won't break.
  
  
• if you are unsure of a change, even if its tests are passing, get someone to review it
• make sure you provide a meaningful commit message. The message should contain:
  • the issue number the change is related to
    
  • in the unfortunate event you have to make several unrelated changes in a single commit (which you should avoid as most as possible), make sure every changes is described in the message.
    
  • write a meaningful message. Spending some time to write a meaningful message is very important.
    And it's usually a very small fraction of the time spent on a particular issue, so it's not lost time!
    Finally focusing on your intent often helps you identify potential issue in your commit.
    
  • is the code formatted appropriately ?? (you do have a codign standard right ?)
  
  Here is a potential template:
  

  --------------------------------
  
  #XXXX: one line description of the change
  
  Details: further long description, that can
  be stored in multiple lines. Can also contain
  multiple elements if the change was big
  - changed this
  - changed that
  --------------------------------

  Example of bad commit message:
  
  
  
  • "" (empty message)
  • "fixed the bug"
  
  Example of better commit messages
  
  
  
  • "#344: refactoring the code before implementing feature Xxx. Details: move common code into utils module."
  • "#345: add a caching mechanism in front of the module connecting to the Customer Information server to reduce and speed up communications. Details: the cache is configurable thanks to a property stored in the database. No User Interface option to change this value yet."

Last tip

Just before you commit, review the changes in the files selected as part of your upcoming commit. Is your commit message good enough ? Did you forget a file ? Do you need to split your commit ?