Skolelinux SVN Guidelines

Why do we use SVN?

• SVN stores all the project files, and all the changes that have ever been done to the files. The possibilities are endless: We can review changes, undo changes, retrieve the project files from any given date, and much more.
• SVN lets many developers work together on the same project, and even work on the same files at the same time.
• SVN tells us:
  • What was changed;
  • When the change was made;
  • Who changed it, and;
  • Why it was changed.

Update often

• Avoid SVN conflicts by running svn update often. The longer it takes before you update, the harder it will be for SVN to merge your changes with the changes done by other developers.

Communicate

• Don't start working on something big without telling anyone. Nothing is more irritating than discovering that you and another person have been working all day on the same issue.

Think twice

• Any changes to SVN can be undone. However, if you commit broken code, and the code spreads automatically to hundreds of live Skulelinux servers, then we're in trouble.
• Run svn update before you commit, to make sure your file is up to date. Otherwise, you risk overwriting changes that other people have done in the meantime.
• svn status is a handy way to make sure you're about to commit the correct files.
• Review your changes with svn diff before committing. This is particularly important with 'live code', that may get copied automatically to the APT repository or the main web site.
• If you don't understand your code, discuss it with other developers on IRC or mailing lists.
• Consider branching if you need to experiment on 'live code'.

Commit often

• Commit every time you're afraid of losing your work.
• Always commit when you're done, don't wait until the next day.
• If more than one developer is working on the same files, avoid conflicts by committing even more often.

One issue per commit

• Don't mix unrelated fixes in the same commit.
• Separate commits makes it easier to review, and if necessary undo, specific changes.
• If a single fix spans several files, then commit all of them at the same time.

Write a good log message

• Make sure you say why you did the change. (SVN already knows who changed it, when it was changed, and what was changed.)
• Write the log message in English, unless you're working on local webpages or translations.
• If the change is really insignificant, try to think of something relevant to say anyway. Short messages like 'typo' or 'formatting' are perfectly OK, if that's all you've done.
• Examples:

  Bad log	Good log
  asdfff	Fixed bug #123 by renaming magik() to magic().
  updated	Updated magic() with a new transmogrification spell.
  more stuff in pci.lst	Added PCI IDs for recent Intel network cards.