Friday, February 2, 2007

Source Control HOWTO

I have started writing a series of articles explaining how to do source control and the best practices thereof. See below for links to the individual chapters in this series. The Introduction explains my motivations and goals for writing this series.

Please note: This is a work in progress. I plan to be adding new chapters over time, and I may also be revising the existing chapters as I go along.

Printer-friendly version: Sorry folks, but I currently do not have this material available in a form which is more suitable for paper. I am planning to eventually publish this material as a book. When that happens, a link will appear here.

Chapter 0: Introduction

Our universities don't teach people how to do source control. Our employers don't teach people how to do source control. SCM tool vendors don't teach people how to do source control. We need some materials that explain how source control is done. My goal for this series of articles is to create a comprehensive guide to help meet this need.

Chapter 1: Basics

Our discussion of source control must begin by defining the basic terms and describing the basic operations.

Chapter 2: Checkins

In this chapter, I will explore the various situations wherein a repository is modified, starting with the simplest case of a single developer making a change to a single file.

Chapter 3: File Merge

Many software teams have discovered that the tradeoff here is worth the trouble. Concurrent development can bring substantial gains in the productivity of a team. The extra effort to deal with merge situations is usually a small price to pay.

Chapter 4: Repositories

A file system is two-dimensional: its space is defined by directories and files. In contrast, a repository is three-dimensional: it exists in a continuum defined by directories, files and time. An SCM repository contains every version of your source code that has ever existed. The additional dimension creates some rather interesting challenges in the architecture of a repository and the decisions about how it manages data.

Chapter 5: Working Folders

The repository is the official archive of our work. We treat our repository with great respect. In contrast, we treat our working folder with very little regard. It exists for the purpose of being abused. Our working folder starts out worthless, nothing more than a copy of the repository. If it is destroyed, we have lost nothing, so we run risky experiments which endanger its life.

Chapter 6: History

There is nothing endearing about a development team that can't find something when they need it. A good SCM tool must do more than just keep every version of everything. It must also provide ways of searching and viewing and sorting and organizing and finding all that stuff.

Chapter 7: Branches

Nelly has a friend who has a cousin with a neighbor who knows somebody whose life completely fell apart after they tried using the branch and merge features of their source control tool. So Nelly refuses to use branching at all.

Chapter 8: Merge Branches

Successfully using the branching and merging features of your source control tool is first a matter of attitude on the part of the developer. No matter how much help the source control tool provides, it is not as smart as you are. You are responsible for doing the merge. Think of the tool as a tool, not as a consultant.

Chapter 9: Source Control Integration with IDEs

Just as a spice rack belongs near the stove, source control should always be available where the developer is working.

Here's a list of chapters I am thinking about writing:

  • A chapter on integration with bug-tracking and automated builds

  • A chapter on common mistakes people make when using source control.

  • A chapter on remote access (client/server, binary deltas, security, ...)

  • A chapter on importing from one source control tool to another

  • A chapter on cross-platform issues

  • A chapter on writing custom tools which access a source control server

  • A chapter on miscellaneous stuff that doesn't fit anywhere else (share, pin, cloak, shadow folders, email notifications, browser-based clients, keyword expansion, ...)

No comments:

eXTReMe Tracker