Version control is an integral part of team-based development. A version controlled data model has changes tracked with each save, giving a full record of how the model evolves over time.
In its simplest form, the history of your data model is a series of versions from the initial versions to the current one.
Each change is called a version, and each version consists of one or more messages describing how it has changed from the last version. These messages called merges. The messages allow committers to describe why they've made the given changes, with one message per high-level change.
Versions are identified by a series of numbers like x.y.z-b. The x (sometimes called
the major
), y (minor
), and z (patch
) numbers are set when
creating releases, and the b (build
) with each subsequent version,
resetting to one at each release.
The simplest style of development, sometimes called trunk based development
, is when all changes to the data
model occur in sequence following the initial merge. All developers work on the main
branch, which is created
with the first version (branches are covered in the next section). This requires that all participants be committers to
the main
branch.
In this example, only a single change occurs per version. In more realistic development, versions have multiple merges.
While this model works well for small teams with reliable feature development, it can fall short when there are multiple, parallel tracks of development.
Since orb breaks down version differences into merges, it's possible for the differences between any two versions to broken down, component by component.
A central part of version control is understanding the differences between versions.
orb presents differences on a component-by-component basis, allowing developers to quickly see what
kind of changes transpired. Components
are high-level changed objects: structures, fields, enumerations,
enumeration items, and so on. Component changes may be additions, removals, or modifications.
This example shows two version differences: a modified field id in the users
structure, and an additional field rid. Components that have no changed, such as the
sess structure, are greyed out.
By clicking on the users structure, the changed components are highlighted in black (for
modified) and blue (for added). Clicking on any shared component will expand it for both the old and
the new versions.
Normal development involves multiple branches
of independent development, where one more
developers work within different branches, then merge their changes back into a shared branch.
A branch
is a central concept of version control that describes a series of versions. There's always an implicit
branch, the main
branch, created when the first version is committed. Developers can create branches at
particular versions: when they make changes, these changes are part of the new branch. Branches may be subsequently
merged to incorporate changes from the original and new branches.
In this example, a new branch newbranch is created and some changes made on it. These changes are then
incorporated back into the main branch.
In team-based development environments, there's often a practice of change review. orb supports signing off on change requests, although doing so optional.
Request reviews are a strong focus of many development paradigms—they encourage development best practices in having more than one data modeller examine changes. In orb, changes may be proposed instead of directly saved by selecting the merge request option during an edit session.
In this example, a user has requested a simple change by selecting the merge request
option
instead of directly merging into the branch. The request shows up in the review panel.
A committer may then mark the changes as reviewed. The identify of this individual is known as the reviewer, and visible in subsequent analysis.
Lastly, reviewed requests may be selectively merged into the branch. Unlike in the other edit methods, there is no facility to create a merge request from merge requests. That's just silly.
Using merge requests not only establishes a more robust audit trail, it encourages incorporating development best practices into your data model development.
While each version increases the version identifier, it's also possible to create releases that increment the major, minor, and patch numbers.
Branch committers or owners can create releases of their data model that increment the major, minor, or patch numbers in the familiar x.y.z notation. (The x.y.z-b suffix automatically increments with each new version.) Releases should follow semver semantics, although this is not (currently) enforced by orb.
Releases create a new version on the branch, with the only difference from the last version being the incremented numbers. Release numbers are specific to a branch: incrementing one branch to, for example, 0.2.3 while the trunk is at 0.2.2 does not affect the trunk. If the branch is merged back into the trunk, the version number follows the trunk's designation (i.e., it would be 0.2.2-2, if the trunk version prior to merging were 0.2.2-1).