Beruflich Dokumente
Kultur Dokumente
for
Developers
Moganedi Sekele
2010-05-24
Change History
1.2 Definitions
Terminology Description
Best Practice A technique, method, process, activity, incentive, or reward that
is believed to be more effective at delivering a particular
outcome than any other technique, method, process, etc. when
applied to a particular condition or circumstance.
Source Control The management of changes to documents, programs, and other
information stored as computer files.
2. Overview
This document presents source control best practices. The need for the existence of this
document was motivated by the desire to encourage proper use of source control. A proper
usage of source control ensures the existence of a reliable code base for production bug fixing
and for developing new features.
The presentation is not exhaustive. For example, the document does not discuss basic
commands of a source control system. It is assumed that readers already possess or will
acquire such knowledge from other materials.
3. Target Audience
This document is geared for developers.
4. Committing Changes
4.1 Explain Each Commit Completely
Each commit must be accompanied by a brief comment explaining the reason for the change.
The comment should provide information on what was changed and why it was done.
1
Source Code Control Best Practices Continuous Integration and Automated Deployment
5. Repositories
5.1 Use an Appropriate Repository Layout
There are different repository layouts in use each with its own merits and demerits. Whatever
the repository layout is chosen, it should be consistent across different projects. The
recommended repository layout for Subversion is a separate repository for each project. A
repository contains exactly three subdirectories namely trunk, branches and tags. Among the
many advantages of the repository layout recommended here, is the ability to set different
policies for different projects.
2
Source Code Control Best Practices Continuous Integration and Automated Deployment
6. Working Copies
6.1 Keep in Touch with the Repository
Update a working copy every time before doing any work and before committing work to
ensure that all conflicts are resolved.
7. Builds
7.1 Build Early and Build Often
Building early and often helps in identification of issues that may arise from committing in
wrong files or application level issues that might have slipped passed individual developer
builds.
3
Source Code Control Best Practices Continuous Integration and Automated Deployment
Annotate A command used for listing the latest version of each program’s source code line
together with the date and file version it was introduced, and person who committed it.
Backout To undo the effects of a commit, often by introducing a new commit that restores
things to the state they were before. Developers who consider a change to be in the wrong
direction, may ask its committer to backout that change.
Branch A set of evolving source file versions. A branch is identified by a tag. Often a branch
identifies the file versions that have been or will be released as a product release. See also
development branch, feature branch, maintenance branch, release branch, security branch,
stable branch, trunk, vendor branch.
Code freeze A period during which non-critical changes to the code are not allowed. See also
commit window. See also slush.
Checkout A command for obtaining a local view of a branch or file; also the corresponding
act.
Commit To integrate the changes made into a developer’s private view of the source code, to
a branch accessible through the version control system’s repository.
Commit window A time period during which commits are allowed for a specific branch. In
some development environments commit windows for a maintenance branch may only open
for a short period a few times a year.
4
Source Code Control Best Practices Continuous Integration and Automated Deployment
Conflict A change in one version of a file, which can not be reconciled with the version of the
file it is applied to. A conflict can occur when versions from different branches are merged or
when two committers work concurrently on the same file.
Development branch The branch where active product development takes place. A product
build from the development branch will have the latest features, but is also likely to be
immature and unstable.
Diff The (typically line by line) difference between two versions of a file or a complete
project. This can be expressed as editor commands that an editor or a tool like patch can
automatically apply, or in the form of a context diff, which by showing lines around a change
is readable by humans.
Feature branch A branch created for developing a particular set of features. The branch is
typically not released, but at some point it is collapsed back to its parent branch.
Feature freeze A period during which no new features are added to a specific branch. This
allows the branch to stabilize for a release. See also slush.
Frozen branch A branch where no development takes place, either in preparation for a
release or because active development has ceased on it.
Head The forefront of a branch, which contains the evolving versions of the source tree. A
release coming out of head will have the newest features, but is also likely to be unstable.
Merge To combine different changes to the same file. Many systems follow the optimistic
strategy of combining all lines that do not conflict.
Merge from current To merge changes from the current branch into the stable branch(es).
In order to avoid disruptive changes in a stable branch, code changes are typically first
introduced into the current (development) branch, tested, and then merged-back.
Module A set of source code files under version control that can be manipulated together as
one.
5
Source Code Control Best Practices Continuous Integration and Automated Deployment
Release A version of the software that is made formally available to a wider community.
Typically each release is identified with a unique tag, and often starts a separate maintenance
branch.
Release engineer The person responsible for coordinating development toward a release. The
release engineer will monitor pending issues for a given release, oversee the code freeze, and
tag the release, once it gets out of the door.
Repository The location where the version control system’s data for a given project is stored.
A repository can be a set of files, a relational database, or a custom-built data structure.
Security branch A branch, created at the time of a release, to which only security commits
are made.
Slush (Referring to code or features). A preparation for a feature freeze or code freeze.
During this period developers will commit code they have been working on, but are
discouraged from starting to work on new elements. Sometimes if a freeze lasts for a long
time a slush may be introduced to ease its passing by allowing in some extra elements.
Stable branch A branch where stability-disrupting changes are discouraged; the branch used
for releasing the stable production-version of the product.
Synchronize 1) To pull in the changes made in a parent branch into its (evolving) child (for
example feature) branch. See also integrate. 2) To update a view with the current version of
the files in its corresponding branch.
Tag A symbolic name assigned to a specific release or a branch. This provides developers
and end-users with a unique reference to the code base they are working with.
Tag slide To apply the same tag to a changed version of a file to correct a last-minute error
found in a release.
Tinderbox An automated build and regression testing tool. A tinderbox will typically fetch
on a regular basis the latest versions of the software from each supported branch, build it for
the different platforms, and report the results from the build and the regression tests.
6
Source Code Control Best Practices Continuous Integration and Automated Deployment
Trunk The software’s main line of development, the main starting point of most branches.
The trunk can often be distinguished from other branches by the version numbers used for
identifying its files, which are shorter than those of all other branches.
Vendor branch A branch used for keeping track of versions of imported software.
Differences between successive versions can then be readily applied to the locally modified
import.
Working copy A developer’s personal copy of a branch. Changes made to a working copy
are eventually committed to its corresponding branch. A working copy will hold the sources
as they were at the time when they were retrieved and requires an update to synchronize them
with the current version.