Principles of Agile Version Control: From Object-oriented Design to Project-oriented Branching


The CBDP is the equivalent of dependency-inversion. The container, as the unit of encapsulation, is the thing that we should depend upon, instead of directly referencing the content or context of the container. The ADP is practically unchanged from its OOD incarnation, and almost not worth repeating, except that dependency management plays an important role in CM. IDIP is a rather interesting translation of the Law of Demeter (LOD) and bears some further explanation.

Evolution Insulation for Unique Identification

The more specific form of the Law of Demeter states that an object method should invoke the methods of only the following kinds of objects:  a) itself, b) its parameters, c) any objects it creates, or d) its direct component objects. In particular, an object should avoid invoking methods of a member object returned by another method.

In version-control, the containers we use don't really have methods beyond the operations provided by the version control tool. However, there are a couple of things that we end up doing with the tool that come pretty close to being methods or services provided to the rest of the CM system and its users: identification and status-accounting.

Identification of a container is the unique name that we give it in the version repository. These would be the names of things such workspaces, codelines and branches, version labels/tags, and change-sets/change-tasks. We usually try to provide descriptive names for these types of containers that will mnemonically suggest their intended meaning and purpose. When any of these names are used in long-lived queries, metrics, or reports and are used to represent unique keys of data that are used when generating such queries, metrics or reports, it can wreak havoc when a name needs to be changed.

Certainly any queries, metrics and reports should program to an interface, not to an implementation when making use of our containers and their data.  In order to avoid similar types of problems, the names of the containers they do use to access that data need to be treated in a similar fashion. This gives rise to an equivalent of the Law of Demeter for configuration identification.

The Identification Insulation Principle (IDIP)

The name of a container should be insulated against change by ensuring that it identifies only the following kinds of significant information: its intended purpose, controlling inputs, or immediate content. A name should not identify any parts of its context nor or of its parent/child/sibling containers that are subject to evolutionary change. What this means is that the names of things like workspaces, changes/tasks, codelines, etc., should be named after their content and/or their intent. The identifier used should not attempt to describe any context information or association that might change during the lifetime of the object.

Sometimes it is easy to go overboard with identifying more information than is absolutely necessary in the name of a thing. If the name we give it somehow implies an association with some other object, then it creates an undesirable form of dependency if that association does not last. It creates, at the very least, an inconsistency between what the name suggests and the actual relationship. Also, if that object and its name is frequently referenced by others, in other databases, repositories, queries/reports, or in other scripts, then such an inconsistency can actually break things in the SCM environment.

For example, if a task-branch is used, and if the task is intended to be targeted to a particular release, many may include that release-name in the task branch. If there is any real possibility that the change might go into a different release instead, though, then the name would no longer be accurate. Changing the name at that point could wreak havoc if the name was used as a unique identifier of the change in other repositories, databases, reports, etc.

Similar problems often arise in an organization's document naming conventions, especially if document names contain organizational identifiers and the organization frequently undergoes renaming or restructuring.

Principles of Task-Based Development

Principles of Task-Based Development

The Single-Threaded Workspace Principle (STWP)

A private workspace should be used for one and only one development change at a time.



The Change Identification Principle (CHIP)

A change should clearly correspond to one, and only one, development task.



The Change Auditability Principle (CHAP)

A change should be made auditably visible within its resulting configuration.



The Change Transaction Principle (CHTP)

The granule of work is the transaction of change.



 The first two of the above principles (STWP and CHIP) are derived from the Single Responsibility Principle (SRP). Here's how:

The Single-Threaded Workspace Principle (STWP)

A private workspace should be used for one and only one development change/task at a time. The STWP is basically a statement about multi-tasking. It says that a worker in a dedicated workspace should work on only one thing at a time within that space.  This is done to avoid the overhead, complexity, and interruption of flow that results from frequent context-switching between multiple tasks.

The Change Identification Principle (CHIP)

A development change should clearly correspond to an intended development task (e.g., for a fix, feature, or enhancement). The CHIP is basically saying that development changes should be transparent to the extent that they are intention-revealing. A change is transparent if its container is visible and can be readily used to reveal its contents.  Also, its container or content should clearly identify the corresponding task behind performing the change. This might be accomplished by associating the change with a record in a tracking system, such as a feature, fix, or enhancement.

Last month, we concluded that the OCP translated to the concept of preserving the identity or essence of its container. What does it mean to preserve the essence of a change? Preserving the essence of change means that if we say a change is in the codeline, we have a way of knowing and showing that its in there, both functionally and physically. We must have a way of detecting and identifying its presence, content, and behavior.

The Change Auditability Principle (CHAP)

A change should be made visible within its resulting configuration. The CHAP goes a step further than the CHIP. The CHIP simply says that a change needs to reveal its intent. The CHAP says a change needs to prove its existence in form, fit, and function. CHIP is a promise that the change is authorized and planned, while CHAP verifies that the promise was fulfilled. Taken together, the CHIP and CHAP are about establishing trustworthy transparency for a change/task. We do this by being able to repeatedly and reproducibly demonstrate and report the request, status, and results of a change, as well as the "who+what+when+where" of a change.  The former is often stored and managed in the tracking system and the latter is typically captured within the version-control repository when the changes are checked-out and in.

The principles of package cohesion (REP, CRP, and CCP) all seem to point to the notion of a change as a single, atomic unit.

About the author

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.