Explain base:


Unit Versions and Revisions

Terminology can be confusing. Therefore, I define these two strongly related terms as


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 document release produces a new version.


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

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 me 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. Probably best maintained as separate Units. The older version could be brought to state Discouraged or Deprecated, with a pointer to the newer version.

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 gets published, you will upload a new revision of the first Unit, which will state that fact.

The interpretation of the Units remains as task for an Application. It is not a role which Meshy Space wants to play.

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

After a few weeks, 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 into 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 public document. Internally, this is swiftly fixed, 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.

mark@overmeer.net      Web-pages generated on 2023-12-19