Sie sind auf Seite 1von 10

Source Code Control Best Practices

for

Developers

Draft Version 0.3

Moganedi Sekele

2010-05-24
Change History

Version Date Author Comments


0.1 2010-01-27 Moganedi Sekele Initial Draft
0.2 2010-04-14 Moganedi Sekele Made the document more biased to
Subversion by removing any and all
references to other version control
systems
0.3 2010-05-24 Moganedi Sekele Combined subsections 5.1.1 – 5.1.3 and
5.2.1- 5.2.3
0.4 2010-05-28 Moganedi Sekele Removed all references to project root in
section 5.1.
Table of Contents
Source Code Control Best Practices..........................................................................................1
for 1
Developers.................................................................................................................................1
Draft Version 0.3........................................................................................................................1
Moganedi Sekele........................................................................................................................1
2010-05-24.................................................................................................................................1
1. Abbreviations, Acronyms and Definitions..............................................................................1
1.1 Abbreviations and Acronyms................................................................................................1
1.2 Definitions.............................................................................................................................1
2. Overview.................................................................................................................................1
3. Target Audience......................................................................................................................1
4. Committing Changes...............................................................................................................1
4.1 Explain Each Commit Completely.......................................................................................1
4.2 Group Commits Logically....................................................................................................1
4.3 Commit Often.......................................................................................................................2
4.4 Commit Only Necessary Artefacts to the Repository...........................................................2
4.5 Review Changes Before Committing Them.........................................................................2
4.6 Resolve Merge Conflicts.......................................................................................................2
5. Repositories.............................................................................................................................2
5.1 Use an Appropriate Repository Layout................................................................................2
5.2 Use a Sane Branching Policy................................................................................................2
5.3 Control Access to Repositories.............................................................................................2
5.4 Monitor Events on the Repositories......................................................................................3
6. Working Copies......................................................................................................................3
6.1 Keep in Touch with the Repository......................................................................................3
6.2 Do not Use Working Copies for Non-Development Work...................................................3
6.3 Do not Share Working Copies..............................................................................................3
6.4 Do not Work Outside Working Copies.................................................................................3
6.5 Update Working Copies after Every Commit.......................................................................3
7. Builds......................................................................................................................................3
7.1 Build Early and Build Often.................................................................................................3
7.2 Automate Build Process Completely....................................................................................3
8. Source Control Glossary.........................................................................................................4
Source Code Control Best Practices Continuous Integration and Automated Deployment

1. Abbreviations, Acronyms and Definitions


1.1 Abbreviations and Acronyms
Abbreviation Description
IDE Integrated Development Environment

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.

4.2 Group Commits Logically


Include all of the repository changes necessary to complete a specific task and nothing else. A
task might be a bug fix or a new feature. That is, only make changes that are necessary for a
particular release and do not be tempted to do more. Committing files that span more than one
task inevitably leads to long commit messages and makes it difficult to undo the changes.

1
Source Code Control Best Practices Continuous Integration and Automated Deployment

4.3 Commit Often


Commit each change to the repository as soon as it has been completed and quality assured.
This practice promotes concurrent development which advocates that all developers on a
particular project be aware of ongoing changes on a regular basis.

4.4 Commit Only Necessary Artefacts to the Repository


Commit only items that are necessary for a build and nothing else. That is, commit only
edited source code and not generated code such as executables, libraries or IDE
configurations or settings. The only exceptions to this practice are third party jars and code
that is built with special tools.

4.5 Review Changes Before Committing Them


Reviewing changes ensures compliance to practices 4.1, 4.2 and 4.4.

4.6 Resolve Merge Conflicts


Conflicts result from violations of practices 4.3 and 6.1. This practice is intended to
encourage the culture of committing changes frequently so that any conflicts can be detected
early and fixed quickly. Conflicts that are left undetected for long time can be very
challenging to resolve.

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.

5.2 Use a Sane Branching Policy


There are many different branching policies or strategies. Choosing a branching policy is
largely to support a stable project trunk at all times. Having said that, the recommended
Subversion branching policy is to branch when needed. The branch-when-needed policy is
characterised by the following practices:

• Users commit their day-to-day work on the trunk.


• Trunk must compile and pass regression tests at all times.
• A single commit or change must not be too large to discourage peer review.
• If there is a conflict between practices two and three above, then a branch is created and
work is done in the branch. Once work in the branch is completed, the branch is merged
back to trunk.

5.3 Control Access to Repositories


Practice user access control through authentication so that change history/audit can be kept.

2
Source Code Control Best Practices Continuous Integration and Automated Deployment

5.4 Monitor Events on the Repositories


Monitoring repositories affords one a chance to start appropriate processes on occurrence of
certain events. For example, upon each commit, a new build can be initiated.

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.

6.2 Do not Use Working Copies for Non-Development Work


If you need to checkout files from the repository with no intention of making changes to
them, for example to create an archive or to do an automated build, use a temporary location
and not a working copy. This can be accomplished by using Subversion’s export command as
code checked out this way is not tracked.

6.3 Do not Share Working Copies


Working copies should be unique for each developer or project.

6.4 Do not Work Outside Working Copies


Working copies can be regarded as controlled areas within which a source control system
tracks changes made to source files. Working outside a working copy is only suitable for non
development work as advised in section 6.2.

6.5 Update Working Copies after Every Commit


The reason for updating a working copy after committing is necessitated by Subversion’s
concept of mixed revision working copies. Mixed revisions imply that committed artifacts are
at the head revision whilst all other artifacts are at an older revision. Updating a working copy
brings all other artifacts to the head revision. Mixed revisions allow commit of individual
artifacts in a working copy. However, there are exceptions to this. Two of these exceptions
are an attempt to commit a deleted file or a directory which does not have a working revision
of head and attempt to commit a property change to a directory which does not have a
working revision of head.

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.

7.2 Automate Build Process Completely


Automating the build process guarantees that the build is repeatable and consistent every time
it is executed.

3
Source Code Control Best Practices Continuous Integration and Automated Deployment

8. Source Control Glossary

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.

Blame See annotate.

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.

Collapse To terminate development on one branch by integrating it with another.

Checkin See commit.

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 message An explanatory message accompanying a commit. The message often


contains a brief description of the change, its rationale, names of contributors, reviewers, or
approvers, a reference to third party software from which the change was obtained, a schedule
for integrating it to other branches, and a reference to the issue identifier associated with the
change.

Committer A developer with commit privileges. Knowing on a personal basis a committer


for a particular product or project can be a valuable asset, because it provides one almost
direct access to the software’s evolution.

Commit privileges A person’s authority to commit changes. Sometimes privileges may be


associated with a specific part of the product (for example, artwork or documentation) or a
specific branch.

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.

Current branch See development branch.

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.

Head branch See trunk.

Line of development See branch.

Label See tag.

Log message See commit message.

Lock An exclusive permission to edit a file.

Maintenance branch A branch where most development concerns bug fixes.

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.

Praise Synonym for blame; see annotate.

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 branch A branch following a specific release of the software.

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.

Revert See backout.

Revision Numbered snapshot of the full repository tree after a change.

Roll back See backout.

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.

ToT See top of trunk.

Top of trunk The head version of the trunk.

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.

Update See synchronize (2).

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.

Version An identifiable instance of a specific file, or release of the complete system.

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.

Working directory See working copy.

Workspace See working copy.

Das könnte Ihnen auch gefallen