Version Control Systems 101

From Mpich
Revision as of 16:23, 17 May 2017 by Raffenet (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

(Attention: This page should be merged into If you are looking for MPICH git workflow, you should definitely go to that page)

To help get everyone up to speed on the way we use VCS, specifically Git on projects like MPICH, we've put together this Wiki page as a reference. Some of the content here may be remedial, but please go through all of it to make sure you're contributing code in the way that everyone else on the team expects. This tutorial will cover:

  • What Goes into Making Each VCS Commit?
  • What Makes a Good Commit?
  • Interoperation with Trac
  • Git workflow (This is a short version of an excellent and much more extensive post (Git)

I will assume that you're familiar with what a Version Control System is and why we use it. If you need a good introduction on VCS in general, you might try one of the many tutorials available on the web (citation needed).

What Goes into Making Each VCS Commit?

Sample Git Commit
  1. Header - This includes:
    • The hash identifying the commit. We usually only use the first 8 characters as this is all that Trac looks at. You can get those by adding --abbrev-commit to your git log command.
    • The original author of the commit. This may be different than the person who originally wrote the commit if they do not have write privileges.
    • The date of the original commit. Again, this might be different than when it was actually pushed.
  2. The Subject of the commit. This describes the actual changes in the commit and is critical to be both textually useful and correctly formatted. More on this later.
  3. The sign-off from another developer (if necessary). Anything that's not a trivial change (and sometimes even those) needs to be reviewed by another developer who is qualified to certify that your code is correct and formatted well.
  4. The code diff. This is the patch itself.

What Makes a Good Commit?

Single Idea Per Commit
  • Only have a single idea per commit
    • Often just a single file or a few lines.
    • Makes automated testing much easier
      • If your commit includes features A & B and we have to roll it back to fix B, we don't want to lose A as well.
    • Code refactoring should be separate from everything else.
      • If you need to change API calls, that should be completely separate.
  • Don't pollute code that isn't yours - Try to make the least intrusive version of your change as possible. Don't try to fix things like whitespace in the same commit as code changes. If it's absolutely necessary to reformat existing code to make it more readable, that should be a separate commit.
    • Doing this makes it hard to separate out who actually wrote the code.
  • Format the code in the same style as the existing code
    • If the existing code uses tabs instead of spaces, continue to use tabs. Again, if the code needs to be reformatted, make that a separate commit.
Bad Whitespace Example
    • This includes new whitespace at the end of the line or lines that only contain whitespace.
    • Catch this early by turning on highlighting in your editor or using git show.
      • VIMRC
        • autocmd ColorScheme * highlight ExtraWhitespace ctermbg=red guibg=red (this goes before colorscheme)
          highlight ExtraWhitespace ctermbg=red guibg=red
          match ExtraWhitespace /\s\+$/
          autocmd BufWinEnter * match ExtraWhitespace /\s\+$/
          autocmd InsertEnter * match ExtraWhitespace /\s\+\%#\@<!$/
          autocmd InsertLeave * match ExtraWhitespace /\s\+$/
          autocmd BufWinLeave * call clearmatches()
      • EMACS
        • (setq-default show-trailing-whitespace t)
Good Commit Message
  • Write a good commit description
    • The first line should be a short (<50 characters) description of the change.
      • Git uses this for the short version of the log
    • Use a blank line between the first line and the rest of the description
    • Write a complete description of the code change in the body.
    • Use correct punctuation, spelling, and cApItaLizAtIOn
    • Good blog post about how to do this correctly
Commit Messages to Trac
  • Refer to Trac tickets in your commit messages
    • Using keywords makes Trac do magic to automatically attach commits to tickets
      • Fix #1234
      • Fixes #1234
      • Resolves #1234
      • Ticket #1234
      • See #1234
      • #1234

General Rules of MPICH Code

  • Read and follow the Coding Standards
  • Use 4 space indents, not tabs
  • Don't leave extra whitespace!
  • Comment everything that isn't completely obvious
  • Wrap code text at 80 characters
    • 72 for Git commit descriptions
    • 50 for Git subject lines
  • Use established naming conventions
  • Check all return values!