blog dds

2005.09.02

Version Control Talk Demystified

One indication of the importance an endeavor has in our lives is the vocabulary associated with it. If developers employ a tool or a method, inevitably they will come up with words to describe their corresponding work in an accurate and concise way. I recently heard a colleague describe version control systems (also formally known as configuration management tools) as boring. I hope that this dictionary will dispel this myth by documenting a rich technical and social vocabulary. If you don’t work with a VCS I believe this list will give you plenty of reasons to look at what these systems can do for you and your projects. On the other hand, if you already use a VCS I hope you will find ideas on how to use it more productively and how to improve your configuration management process. And, no matter to which group you belong to, I am sure you’ll find here some new words worth knowing.

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.

attic: The repository location containing files that do no longer belong to the head branch (CVS).

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. See also hostile backout.

backout war: See commit war.

bike shed discussion: A discussion about a simple and trivial issue where everybody can have (and often has) an opinion. The name of this term refers to an example given by Cyril Northcote Parkinson (Parkinson's Law, and Other Studies in Administration, Houghton Mifflin, 1962): a proposal to build a nuclear power plant may pass through the board of directors without a comment, whereas a proposal to the same board for building a bike shed can get entangled into endless discussions. The reasoning is that the complexity of a nuclear plant daunts the members from commenting on it—they assume that someone else has checked it; on the other hand, because members will be familiar with building a bike shed, they will comment on the proposal to contribute to the board and make their presence felt.

blame: See annotate (Subversion).

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.

bug report: See issue.

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.

check-in: See commit (RCS, ClearCase).

check-out: A command for obtaining a local view of a branch or file; also the corresponding act. (ClearCase, CVS, RCS).

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. Example: “I’m glad Sue is a Linux kernel committer; she will introduce the patches I gave her to support my new laptop over the weekend. ”

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 war: A series of conflicting and mutually reversing commits introduced by developers who disagree on how a particular element should be coded. A commit war sometimes starts with a hostile backout.

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.

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.

delta: See diff (SCCS).

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.

edit: See check-out (Perforce, SCCS).

errata: Severe service-disrupting bugs for which there is no known work-around. Fixes for such bugs can often be introduced on a frozen branch.

feature branch: A branch created for developing a particular setof 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.

hostile backout: A backout done without prior arrangement by a committer different from the one who introduced the original change. This is usually the opening shot in a commit-war.

integrate: To pull in the changes from one child branch into its parent. See also collapse, synchronize, merge from current.

integrator: A person responsible for resolving conflicts; the person with commit privileges to the trunk (Aegis).

issue: A uniquely identifiable entry in an issue tracking system, that describes a problem or an enhancement. An issue’s record apart from its identifier and brief description, often also identifies the environment associated with it, its status, severity, priority, and resolution, dependencies, details on replicating or solving a problem, the persons associated with it, attachments, and its change history. Also known as a bug report or problem report.

line of development: See branch.

label: See tag.

log message: See commit message.

LOD: Line of development; see branch.

lock: An exclusive permission to edit a file.

main: The default branch or trunk. (ClearCase).

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. .

MFC: See merge from current.

module: A set of source code files under version control that can be manipulated together as one (CVS).

pointy hat: A virtual headgear element, similar to a dunce cap, humorously awarded to committers for acts of carelessness or stupidity. Typical acts worthy of a pointy hat include committing code to the wrong branch, code that does not compile, or code that is obviously wrong. The award is typically made though the commit message of the corresponding fix.

praise: Synonym for blame; see annotate (Subversion).

problem report: (PR) see issue.

project: See module (MKS Source Integrity).

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.

revert: See backout.

reparent: To move the changes developed under one branch into another. The changes are not committed to the original branch.

repo bloat: Changes recorded in the repository that do not contribute anything useful to the project’s history (for example a large erroneous commit and its associated backout operation). Repo bloat can be reduced through repo surgery.

repo copy: To change the location or name of source code elements in the repository around, while preserving their change history. This is one example of repo surgery.

repo fix: See repo surgery.

repo master: The person in charge of the version control system’s repository. One who has rights to perform repo surgery.

repo surgery: Changes made directly to the version control system’s repository, bypassing the system’s commands. For example, the changes can be made by issuing database commands or by directly manipulating system files. Through repo surgery one can perform operations not directly supported by the version control system. See also repo copy, repo master.

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.

roll back: See backout.

sandbox: See view (MKS Source Integrity).

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 (Perforce).

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. (CVS)

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.

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) (CVS).

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. (CVS, Subversion)

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

view: A developer’s personal copy of a branch. Changes made to the view are eventually committed to its corresponding branch. A snapshot view will hold the sources as they were at the time where they were retrieved, and requires an update to synchronize them with the current version; a dynamic view always keeps the files synchronized with the current version (ClearCase).

workspace: See view.

working copy: See view.

Many thanks to Christian Brueffer, Wilko Bulte, Garance Alistair Drosehn , Eivind Eklund, Julian Elischer, Ruslan Ermilov, Giorgos Keramidas, Isidor Kouvelas, Bruce A. Mah, Marcel Moolenaar, Mark Murray, Colin Percival, Wes Peters, Ken Smith, Dag-Erling Smørgrav, Gordon Tetlow, who contributed ideas and comments.

* Parts of this glossary have been published in the IEEE Software magazine Software Engineering Glossary column, and should be cited as follows:

  • Diomidis Spinellis. Software engineering glossary, version control, part I. IEEE Software, 22(5):107, September/October 2005. (doi:10.1109/MS.2005.141)
  • Diomidis Spinellis. Software engineering glossary, version control, part 2. IEEE Software, 22(6):c2–c3, November/December 2005. (doi:10.1109/MS.2005.169)

Read and post comments, or share through   


© 2005 IEEE. Personal use of this material is permitted. However, permission to reprint/republish this material for advertising or promotional purposes or for creating new collective works for resale or redistribution to servers or lists, or to reuse any copyrighted component of this work in other works must be obtained from the IEEE.
This material is presented to ensure timely dissemination of scholarly and technical work. Copyright and all rights therein are retained by authors or by other copyright holders. All persons copying this information are expected to adhere to the terms and constraints invoked by each author's copyright. In most cases, these works may not be reposted without the explicit permission of the copyright holder.
Last modified: Tuesday, December 12, 2006 9:20 pm