[LispM-Hackers] Commit Policy

[James A. Crippen]

JM brought up the question of commit policy with me.  This is always
an interesting issue, and the answer is usually vague.  I've worked on
both open-source and commercial projects using CVS, and have found a
number of rules that help to maintain a happy environment for
developers.

Here's some basic commit policy rules:

* DON'T commit things that won't compile.

  It's *extremely* frustrating to do a 'cvs update' and then suddenly
  find that some random part of the program won't compile, preventing
  you from working on your stuff until you can dike out the breakage
  or revert the files to older, compilable versions.

* DON'T commit binaries (eg, object files, bands, coredumps, etc).

  Why?  Because the CVS repo isn't set up to handle them
  automatically.  If you do really want to add a binary somewhere then
  please discuss it on the list beforehand.  We will decide whether it
  really needs to be in the repo, and if so where, and how to
  correctly handle binary files with CVS (which requires special
  keyword handling).

* DON'T commit output.

  Output belongs on the list, on the webpage, or on personal pages.
  Not in the repository.  Same with debugging dumps.

* DON'T commit platform specific things without non-specific handling.

  Thus, if you're writing code to support FooOS don't commit changes
  to code without properly conditionalizing the support so that it
  doesn't show up on every platform.  Just because you think 64-bit
  support would be n34t on the Alpha doesn't mean that people using
  Vaxen will like it integrated in their build, even if GCC can
  magically make it work.

These are things to think about before you commit something.  Does it
compile?  Is it platform specific with appropriate conditionalization?
Is it text-only?  Etc...

As for when you *should* commit, please commit when you can fulfill
above restrictions.  Here's some rules regarding how commits should be
done.

* Commit regularly.

  Even if the changes you've made are small, try to commit them.  They
  may not seem important to you but someone else may be encountering a
  bug that is fixed by your changes.  If you commit often you will
  also avoid development out of sync with the project.  Your repo copy
  will tend to stay in sync better if you keep your commits up to
  date.

* Commit in semantically related chunks.

  Don't commit the changes you've made in the last week all with one
  commit.  Try to break it up into related chunks and commit each
  separately.  Thus changes to memory management code should be
  committed separately from the graphics code unless they're obviously
  related.

* Use descriptive commit logs, but keep them short.

  Don't use the commit logs as a forum for describing your woes and
  ideas.  The commit logs are just a record for why commits are made,
  and what is included in each commit.  If you find yourself writing
  more than 25 lines of log text then you should take the details to
  the list as a followup post to your commit log mail message.  But
  don't just use one-liner logs like "Fixes bug #422369."  That's
  useful if you happen to be looking at the bug database (which we
  don't have yet, but will).  But most people do not read commit logs
  while looking at the bug database.  If the bug is simple enough or
  has a 'name' then describe or name it, *and* include the bug
  tracking number.

* Try not to spam commits.

  If you've got five thousand and one things you want to commit,
  please don't commit them all at once if you can.  Commit one chunk
  at a time, then leave the repo alone for a while before you commit
  the next thing.  Some people work in a very distracted fashion,
  first hacking one thing, then another.  They build up a big pile of
  unrelated changes and then want to commit them all at once.  Instead
  they should commit one thing at a time, then wait for the other
  developers to evaluate the changes before committing the next set of
  changes.  This keeps other developers from being confused by changes
  that occur all over the source tree in seemingly random ways, that
  might introduce new bugs.

Any other suggestions?  When we all agree on policy I'll put up a web
page for it.

'james

-- 
James A. Crippen <james@unlambda.com> ,-./-.  Anchorage, Alaska,
Lambda Unlimited: Recursion 'R' Us   |  |/  | USA, 61.20939N, -149.767W
Y = \f.(\x.f(xx)) (\x.f(xx))         |  |\  | Earth, Sol System,
Y(F) = F(Y(F))                        \_,-_/  Milky Way.