orb » data modelling

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.

Read more about branches, the trunk, versions, and merges.

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

Read more about releases and versions.