//FIXME -- Jason Felice’s blog

My subversion workflow operates in terms of logical units of work – units which are small, concisely summarizable in a single sentence, and which leave the system in a consistent state.

• Smaller units increase the historical information available to future maintainers. The commit messages for five small commits, each encapsulating one design decision, are more informative than the commit message for one large commit encapsulating five decisions. Smaller units also reduce the risk of lost work.
• Concise commit messages also increase the historical information available to future maintainers. Remember that the future maintainer typically has no shortage of information documenting how the system works (i.e., the code), and not much information documenting why the system works that way. Commit messages are often the most convenient vehicle for documenting why.
• The code in version control should always compile in its entirety and pass all existing unit and integration tests. This gives the developer a measure of agility, ensuring that she can track new priorities that interrupt the current task without backing out incomplete features or producing horrible manual builds.

A logical unit of work is usually smaller than a complete customer feature.

Here’s the workflow (I use command-line svn, but there are TortoiseSVN equivalents for mouse users):

1. svn up

   Make sure I have the latest version of the code. “up” is short for “update”, so you could type “svn update” instead.

2. svn st

   Make sure I don’t have any changes I’ve forgotten to commit. If I do, commit them, revert them, or save them to a patch file and revert them, depending on what I intend to do with those changes. “st” could be spelled “status”.

3. Do my “logical unit of work”, coding tests first then making them pass.

4. svn st

   Make sure I didn’t change anything extra. If I did, revert it with “svn revert path“. You are committing a “changeset” representing a logical unit of work, and it’s good hygiene to clear out unrelated things and remember what you touched.

5. svn diff |less

   I review the patch to make sure I haven’t left any debugging prints or made any unnecessary changes. Unnecessary changes frequently happen if I started to do something one way, but then decided to do it another way. less is like more on steroids, allowing you to scroll up and search. I recommend getting a copy if you don’t already have it.

6. svn diff |diffstat

   A completely unnecessary step, but I like seeing the histogram of changes to see if I’ve been able to reduce the lines of production code. diffstat is a separate program that is unrelated to the svn project.

7. svn ci -m "Twiddle the flarp handlers"

   Make the actual commit. If I have two logical units of work in the repo or want to avoid committing a file, I’ll specify the file paths at the end of the svn command-line to limit the commit to one set of files.

   If I need a multi-line description of the changes (perhaps if it fixes more than one bug or I need to leave a comment for future svn spelunkers), then I’ll omit the “-m” option and message and enter a multi-line message in my editor. You need to set SVN_EDITOR= for this to work.