Home

• explain
• schemas
  • ms: base
  • msc: concept
• contact

Explain

• Compare

Explain base:

• Life-cycle
• Revisions
• Namespaces
• Identities

Explain concept:

• Contracts
• Payments

Implementation:

• Messages
• Formats

Infrastructure:

• Components
• Network

Unit Versions and Revisions

Terminology can be confusing. In this case, I defined two strongly related terms as

Version

Two versions of the same thing, are semantically nearly the same. For instance, because they are formatted differently: a document in PDF format and a document with the same text in MS-Word format are two versions of the same. But it could also be an update of the content: a new software release produces a new version.

Revision

Two revisions of the same thing are to be seen as equivalent. The new revision is to be interpreted as perfect replacement for the existing revision. The old revision can be thrown away immediately. For instance, you add a deprecation date to an existing published Unit.

Decide the kind of equivalence

As Collection designer, you have to decide what updates of your Unit payload mean: are they Version changes or Revision changes. Let's give an example with a Collection which represents a Linux distribution (like Debian or OpenSUSE).

Clearly, packages with different functionality have a distinctive name; package libzip is not the same as package thunderbird. They are not different Versions nor different Revisions of the same thing.

What about libzip software version 1.12.3 and version 2.1.8. Are these ideal replacements? A major number change is usually indicative for compatibility troubles.

Can libzip software version 1.4.1 be seen as safe follow-up revision of 1.2.42 in a Unit named libzip-1? Or are software version 1.4.1 and 1.4.2 close enough to share libzip-1.4?

Maybe, you design libzip-1.4.1-pl3 and libzip-1.4.1-pl16 as revisions of the same Unit named libzip-1.4.1. The Client is able to distinguish between revisions of the same Unit: it can still be traced in detail.

But at least, when you deprecate libzip-1.12.3-pl12 because Unit libzip-1.12.4-pl1 is published, you will upload a new revision of the first Unit which states that fact.

Naming schemes

Whether the final version of a written document replaces the concept version of that same document, or coexist in the same Collection is reflected in the naming scheme you design for that Collection.

Say, you have a complex Document as payload for the Unit. Internally in your department, this document sees multiple versions. Those are all kept for historical reasons in separate parallel Units within Collection 2023-business-plan. The Units are named business-plan-v1 and business-plan-v2. The Authors and Owners of those Units are employees of the company.

Finally, the document is ready. The CEO creates a new Unit business-plan in the publicly accessible Collection mycompany/2023-business-plan. She puts the organization Identity as Owner in the new Unit. The new Unit can refer to the internal Unit as source, but does not need to.

Then, after two days, the chair of the company's board discovers that some of the tables were not correctly included in the document. Internally, this is swiftly fixes, leading to a new Unit with a new name. Then, this new version of the Document is uploaded to the public Collection as new revision of the same Unit. No need to keep the broken Document available to the outside world.

This is how you MAY organize it: you can design (and configure) your naming scheme any way you want.