Versioning Architecture Documents

This guide describes the what, why, and how related to the versioning of architecture documents.

Intended for

Architects.

Why versioning an architecture document

Architecture documents describe technical aspects that might change over time and refer to modules, components, subsystems, or an entire system. It is always of interest to know and understand the architecture of the latest release. Due to long product life cycles and long-lasting support agreements, it's sometimes also necessary to know how system parts worked in a previous release, where the architecture was different from the current one.

For this reason, descriptions of architectural changes must be preserved while keeping the architecture documentation as simple and readable as possible.

Versioning of an architecture document

There are two ways to version an architecture artifact:

• Product version: The described module/component shall be integrated into a product (such as 800xA, S+, Freelance) in a specific release (e.g., 800xA 7.0, S+ 3.4).
• Module/Component version: The module/component itself has its own version (e.g. PG2 v2.4, PN800 Connect v1.5).

When documenting architecture, it must be clear which version the presented content refers to.

Versioning basic rules

As a general rule, unless otherwise specified, a wiki page describing architecture content is valid for any product and component/module version.

• If a certain module/component behaves differently for different products (e.g., S+ vs. 800xA), the differences shall be directly indicated on the wiki page in different paragraphs.
• In case of differences among different product/component/module versions, a new wiki page with the same title will be created, and a copy of the old page will be preserved as a "child" of the main one (see further details in the next section).

How to create a new version of an architecture wiki

If a new component/module version requires changes in architecture (and its documentation), as described in the previous paragraph, a new version of the wiki page shall be created. The current version will also be maintained, but the title will be changed before it is moved to the newly created version as a child page.

The reason for creating new wiki pages while also keeping a copy of the old ones is to provide a clear view of the architecture in released products throughout their life cycles (e.g., for troubleshooting reasons).

The changed content shall be added to the new page, preferably by modifying the page structure as little as possible.

NOTE: Keeping the changes to the page structure to a minimum facilitates comparing a newer and older version of the wiki, making it easier to spot the differences in the architecture.

A practical example

The system architecture wiki documents the required OPC UA profiles to be supported in 800xA 7.0. The architecture document defines the list of required profiles in a Markdown file.

When it's time to release a new version of 800xA, for example, version 7.1, new profiles are added to be supported. Since there are still systems running 800xA 7.0, it is necessary to preserve the track of the supported profiles in that release.

As described earlier, the following needs to be done:

• Create a backup version of the "OPC UA Profiles" wiki page, and rename it to "OPC UA Profiles"
• Move the just-created wiki page to a child of the main "OPC UA Profiles" page.
• Update the main "OPC UA Profiles" page with the new required profiles for version 7.1.

NOTE: If in the text of the wiki we mentioned those profiles were required by 800xA 7.0, we will have to modify it with the new version.

Another example of the same architecture content is regarding another product. For example, having the same OPC UA Profiles page for 800xA 7.0, we may also want to add content for S+ 3.4.

In this case, it is recommended to:

• If the content of the two products is the same (e.g., the same profiles are required), mention the product versions in the introduction and then list the profiles only once. If there are substantial differences, create two separate chapters listing the profiles for 800xA 7.0 and S+ 3.4.

Summary

The diagram below summarizes the versioning approach to an architecture wiki page.