Semantic versioning

[ioanacontu]

What needs to get done? Who needs to participate?

---

References:

Video shared by David E: https://www.youtube.com/watch?v=m1i_PVwtL7o at 3:09 Gijora Dammann dives into define what needs to be versionned for a good minute.

Comments from Francis G (captured from this miro board): Again, as a reference in terms of WET-BOEW / GCWeb, we are using a mono-repo that follows Semantic version (as described int the Design Decision here: https://wet-boew.github.io/wet-boew-documentation/decision/6.html ). In fact the WET-BOEW Documentation website, which is different from the main site, is the one we use to publish documents such as Design Decisions and accessibility reports, both for transparency and research purposes: https://wet-boew.github.io/wet-boew-documentation/index-en.html . An example of an a11y assessment would be this one: https://wet-boew.github.io/wet-boew-documentation/research/2020-37-research-a11y-sit.html

Product cycle and versioning API were also both defined through Design decisions, respectively: https://wet-boew.github.io/wet-boew-documentation/decision/9.html and https://wet-boew.github.io/wet-boew-documentation/decision/3.html . As well as browsers supported (DD-2).

FYI, I am just putting all of those references here so that we are aware of where we currently are to better understand where we want to go.

[ioanacontu]

Conversation to start in in the tech syncs this week.

[duboisp]

Bellow is my initial draft on semantic versioning for the design system that I am currently working on. It's still incomplete and will require to be discussed.

---

Semantic Versioning and public API for the Design System (Draft)

Demystify the term

API could means -> A web service used to interact with or to gather information. Like Github GraphQL API, RestFull API... API could means -> A public API explaining how we can interact with a product in a specific point in time. A set of rules where change would happen in the future and are risk managed by a meaningful version number.

What is it?

The semantic versioning is a contract with the product user, which exclude technical implementer, to quickly evaluate the impact on their work when upgrading a dependant library used by it. In other word, it allow to quickly evaluate the risk of applying changes on the published work after the completion of the dependant library update process. This document define the basic public API for the design system by explaining what aspect need to be monitored and how it should be monitored. This public API apply for products and sub-products of the design system.

• Patch: A Patch change of the library means the user don't need to modify their work neither have new feature. But some improvement are included with the latest change. However the library still need to be implemented.

• Minor: A Minor change of the library means the user would have access to new functionality when creating new work or updating existing one. The user could probably need some training. Having new feature could require some communication, usually through different channel, the change at the users. The meaning of a patch change are included in a minor change.

• Major: A Major change of the library means the user must apply change on their published work otherwise it would be broken. Upgrading to a major change often require some planing and the creation/execution of a migration plan. The meaning of a minor change are included in a major change.

The library implementation details are out of scope by default of this versioning public API. However, for some library, depending of their purpose or their audience, might include some implementation details in their public API variant. When possible, leave those implementation details in the release note of the library along with changes description applied in the version.

Implementation via sub-system between the user and the library

The risk of requiring to apply a change can be direct or indirect. It is an indirect change when the dependant library is implemented through a sub-system which manage some aspect described by the public API.

[Next paragraph need to be rewritten] A library that is implemented in a subsequent system before to reach out the user could transfer some requirement of changing the published work from the user to the implementer. So it is possible to get the major (breaking) changes fully managed and to lower the risk impact on the user.

For example, here a major change to a library that are transformed into a patch change for the user by implementers. Let say a major version of the GCWeb library is released which require to apply some HTML markup change for the contextual feature component. For the GCWeb library, the user is the web editor that only/directly use the library to produce a web page. Let say that GCWeb library are implemented in a web content management system, like Adobe Experience Manager (AEM) and AEM have a component with a graphic user interface (GUI) to help the user to configure the contextual feature component. The HTML markup produced are not controlled by the user but instead by the AEM component. Then, for the user this change in the GCWeb library don't impact them, but it will impact and require some development work by the library technical implementer to apply the HTML markup change at the component level. In that situation, the user should follow the versioning of the subsequent system. Like in the previous scenario the GCWeb change should be measured by an incrementation of the patch number of the subsequent system.

What to version:

Formally, each component (individual feature) and the product (library) should carry their own version number. The product version to help users to be aware that changes happen in the dependency. The component version are to help more precisely the user about what change should be applied strictly at the component level in the context of a product (library). The third type of version are to provide guidance to stakeholder that are working on the development of the actual component. It is used to identify if the changes, along with how it is applied, are going to impact the version of the component. In some situation, a major/minor change can be avoided by applying the change request differently, like leveraging JavaScript to avoid a change in the HTML markup.

3 Type of version

Product (Library)

A system or a tool that directly support the design system mostly composed of a set of components.

For example:

• Design tokens library
• Guidance book
• Reference implementation (ex: GCWeb)
• Shape graph (for future)
• --- stikeout --- Variant implementation of the design token library + reference implementation. For example: Adobe Experience Manager (AEM), Drupal WxT, CDS web form solution...---

Component (Feature)

Design patterns of organic feature which are used to create uniform and common digital experience for published creative work. This group represent component at different atomicity level. Sub-atomic, atomic, molecule, organic and template.

For example:

• Alert (organic)
• Contextual feature (organic)
• Institutional profile (template)
• Button (atomic)
• Form email field composed of label, input, required marker, inline error bloc (molecule)
• Base font (sub-atomic)
• Color palette (sub-atomic)

Component composition (Architecture Aspect)

[[ TODO: Find a better name for this sub-division of a component and to avoid the confusion of re-using the word "component" here. Francis G. proposed to rename it for "component aspect" and then in the description we only refer to "aspect" without the qualitative word "component"]]

Pieces that, put together, define what a component is. A component might not include all the sub-pieces, but changes applied to individual or more pieces impact component users (Designer, Framework implementer, Web publisher, Content author). Each pieces carry its own version number. When needed, product can be more specific on how it get measured.

Composed of:

• Layout (Wireframe)
• Style (CSS)
• Semantic (HTML)
• Interaction pattern (Functional event listing)
• Context of use (Guidance)
• Configuration (Customization description)
• Static data (Block of i18n text string)
• Schema (Shape graph; data layer)
• Component essential dependencies (List of major versioned component)

Component scope

For example, a web page is sectioned like: page header, content, site footer... Components are designed to use only in one of those section. Bellow are generalized scope that can applicable for various like website, mobile apps...

Type of layer:

• Globals/Foundation: Applicable for every pages including when defining template and providing design baseline for creating components. Like:
  • Base font size, colour and family
  • Default text colour and background colour
• Product wide level: Applicable for the majority of contents. This usually is about components that relates to common header and common footer. For some product, the wide level could include the globals scope for brevity and simplicity. Like:
  • Top right search bar
  • Top menu button
  • Contact us link in the footer
• Main content level: Component that are applicable for main content area. Like:
  • Video player
  • Overlays
  • Form validation
• Template level: A named set of components designed to be used in a specific context. Component listed in the generic product wide level and generic Main content level could be optional. Template level might include exclusive components scoped to be at site level and main content level. Like:
  • Transactional page
  • Topic page
  • Institutional page
  • Splash page

How to evaluate a version number.

The following are to help to identify if the version number need to be incremented by first evaluating the component composition.

For:

• Library: Version number is at least based on the set of supported components. Specific library might includes other characteristic in their public API, like the packaging. -TBD move in another section-- The component title (optionally its corresponding technical name) must be a common language between all libraries under the design system. --END TBD--
  • Major: A component is removed
  • Minor: A component is added
  • Patch: A component is updated with no additional feature
• Component: Version number is based on a combination of the applicable component composition. -TBD move in another section-- Not all component composition may be applicable to the component. --END TBD--
• Component composition: Represent attributes (specification area) that define what is the component. Each composition element have their own version number. A specific library, like the reference implementation GCWeb, might add some specificity on how those component composition version are evaluated and mitigated in the product (library).

Component composition:

Layout (ex. Wireframe)

Defined by how atom and molécule pieces are organized among others within a component. Multiple layout can be supported for the same component. A layout can contain sub-layout which correspond to a bloc. ---Probably to remove--Removing or adding pieces create more sub-layout variant.--

• Major layout change: When a defined sub-layout is removed or reorganized. Merging two sub-layout is considered reorganized.
• Minor layout change: When a new layout variant is added.
• Patch layout change: N/A

Library variant:

• Reference implementation (GCWeb)
  • Major: When a defined sub-layout is removed or a reorganization that require web author/web developer to update their existing pages.
  • Minor: When a new layout variant is added.
  • Patch: A reorganization that can be applied without changing anything exception of implementing (installing) the updated library. That means the changes is fully managed by the library.

Example of metrics:

• Wireframe
• Rendered HTML that leverage a CSS positioning mechanism (ex. grid system)

Style (ex. CSS):

Define the visual aesthetic of a component.

• Major style change: Significative changes that change the meaning of the component or/and directly imply a major change in another component composition (like Layout, Semantic...).
• Minor style change: The addition of a new styles in order to visually enhance the component based on addition of a new configuration.
• Patch style change: Update to an existing style or an addition that don't imply a new configuration or an addition that enhance the component with no change in meaning of the component.

Library variant:

• Reference implementation (GCWeb)

  • Major: A removal or a change of CSS class name that provide meaning and require a web author/web developer intervention to update the published content. A style that impact the published content to be reviewed, re-architect, re-organized or re-published to avoid breaking change in the communication (ex. web page). The removal of a styled configuration that is repurposed to a new component or guidance that are updated in a matter to deprecate the use of such configuration.

    For example, increasing the font size from 16px to 20px considerably impact campaign page that are tightly designed to use all the available space without impacting the layout of the promotional content.

  • Minor: The addition of a new style or a new class name that support a new configuration.

  • Patch: Change that can be applied without changing anything exception of implementing (installing) the updated library. That means the changes is fully managed by the library.

    For example, the visual change for the alert component where the alert in a coloured box (Bootstrap 3) is now change to be a large left coloured border.

Example of metrics:

• Set of CSS/SASS rules
• Textual description of the style itemized

Semantic (ex. HTML):

Provide a meaning of the dynamic data (schema) and static data contained, managed and visible through the component.

• Major change: Removal of a dynamic data piece defined with semantic
• Minor change: Addition of a dynamic data piece defined with semantic
• Patch change: Not applicable

Library variant:

• Reference implementation (GCWeb)
  • Major: Removal of an HTML element and/or HTML attribute/value by the users
  • Minor: Addition of HTML element and/or HTML attribute/value by the users
  • Patch: Removal of an HTML element or attribute that don't impact any previous semantic. In order word the previous HTML markup used for coding the component can stay the same, no change required by the users. Or any change (removal, addition, update) in HTML markup that are generated and injected by the javascript.

Example of metrics

• HTML markup ordered and excluding generic element
• Dynamic data item which are link to a semantic tag

--- End of first review (as 2021-09-23) with Pierre D. and Francis G. ---

Interaction pattern (ex. Functional event listing):

Definition of the events supported by component.

• Major change: Removal of an interaction definition or major remodel of an existing interaction that require users to review how the component is used in their content.
• Minor change: Addition of an interaction
• Patch change: Refining the interaction definition or remodel without requiring users intervention.

Library variant:

• Reference implementation (GCWeb)

  This include Javascript callback, it exposed name and list of parameters, where third party application can establish a communication with the component. For example an event name or a globally exposed function with a set of parameters.

  • Major: Removal of interaction that require to update the corresponding HTML markup, like removing an HTML button or a callback.
  • Minor: Interaction pattern that require the user to add a flag in their HTML markup or specify a new configuration in order to activate the continuation. The addition of a new callback.
  • Patch: Update of the Javascript code where it don't require any change by the users (web author). Removal of an interaction where the javascript is applying a workaround solution to avoid a change by the users on their existing published content. The addition of an interaction where the HTML markup necessary for the interaction is injected and fully managed via javascript code.

Example of metrics

• Functional event listing
• List of CSS selector identifying the controller in the HTML markup
• List of callback to interact with the component via code.

Context of use (ex. Guidance):

• Major change: Removal of a practice requiring the user to review and change or adapt their content. Like restricting the scope of use for a component.
• Minor change: Addition of a practice where it expand the scope of the component.
• Patch change: Clarification in the context of use, without requiring the intervention of the user to rethink their published work.

Library variant:

• Reference implementation (GCWeb)
  • Major: Not applicable but it might imply a change in the configuration and/or in the interaction pattern.
  • Minor: Not applicable but it might imply a change in the configuration and/or in the interaction pattern.
  • Patch: Not applicable but it might imply a change in the configuration and/or in the interaction pattern.

Example of metrics

• Guidance

Configuration (ex. Customization description):

Configuration that transform or adapt the plain component to better meet the user need. Providing a configuration should be optional and when it is required it must provide/define default value.

• Major change: Removal of a configuration name or a change in the default value that require a change by the users.
• Minor change: Addition of a new configuration which require somehow to be activated by the user.
• Patch change: Removal of a configuration that don't break the component neither require the user to make update at their published work.

Library variant:

• Reference implementation (GCWeb)

  This include the configuration technical name used in a JSON configuration file or in HTML attribute or as a CSS flag in order to configure the component.

  • Major: Removal of a configuration or a change in its default value which impact the component behaviour/state and require a user intervention in their published work.
  • Minor: Addition of a new configuration.
  • Patch: Removal of a configuration with is managed through a workaround to prevent updating the user to update their published work.

Example of metrics

• Customization description and default value

Static data (ex. i18n text string):

Stateless text used by the component except when changing the language. i18n means internalization.

• Major change: Removal or rewrite of a i18n text string. Addition of a required i18n text string in the component.
• Minor change: Addition of an optional i18n text string
• Patch change: Removal of a i18n text string but if kept it don't negatively impact the published work and so no change required by the user.

Library variant:

• Reference implementation (GCWeb) The key identifying a i18n text string is monitored and not the i18n text value as is. Except if it is added as a text node in the HTML markup of the component which belong to semantic component composition.

  • Major: Removal or addition of an i18n text string that impact published work. Like through its plugin configuration.
  • Minor: Addition of an optional i18n text string
  • Patch: Addition or removal of i18n text string but where a workaround is managed through javascript or CSS without impacting the published work of the user.

Example of metrics

• i18n text string
• unlocalized key identifying a i18n text string

Schema (ex. Shape graph; data layer):

Stateful text or data to deliver information or user experience by using the component

• Major change: Removal of a data or the addition of new pieces of data required by component which require the intervention of the user in their published work.
• Minor change: Addition of an optional data.
• Patch change: Change of a data piece from static to dynamic that don't require any change by the user.

Library variant:

• Reference implementation (GCWeb)
  • Major: Idem
  • Minor: Idem
  • Patch: Idem, but removal or addition that is fully managed through javascript or CSS without impacting the published work of the user.

Example of metrics

• Shape graph
• List of variable

Component essential dependencies (ex. List of major versioned component):

• Major change: Removal of essential dependencies if the user need to review and adapt their published work.
• Minor change: Addition of new dependencies that provide new configurable feature requiring the user to activate it.
• Patch change: Update of the dependencies without breaking any existing published work. Removal and addition that require no intervention from the user.

Library variant:

• Reference implementation (GCWeb)
  • Major: Idem
  • Minor: Idem
  • Patch: Removal where the library are implementing a work around that are not breaking existing published work.

Example of metrics

• List of major versioned component

---

edit: Completed the draft + styled + applied first review changes

[ioanacontu]

To be presented at the next tech sync and with the product team.

[duboisp]

I updated my draft published in my previous comment

[duboisp]

Tel que commenté par @mcman12 ce matin. Il avait suggéré d'inclure le risque d'implémentation d'un produit. Il n'est pas nécessaire d'avoir cette discussion maintenant.

J'ai intentionnellement exclus l'implémentation dans l'ébauche de API publique car, dans notre context au gouvernement, l'implémentation du produit est rarement fait par l'utilisateur du produit pour en produire du contenu.

Au moment venu, il va falloir déterminer la périodicité de la release du Design system. Je propose que le Design system soit un ensemble de produits associés à une version ainsi qu'un descriptif du risque associé à son implémentation. En même temps, ceci permettrait de mettre en place un processus de synchronization entre les divers produits et de s'assurer que les components soit développé ou mis à jour à temps. On pourrait avoir un numéro de version pour le Design System un peu comme Ubuntu "YYYY-MM".

[ioanacontu]

In progress. Need to review with team - we want to insure there is plain language.

[ioanacontu]

Reviewing the public API with Francis. Preparing a presentation for how we will be measuring versioning/changes. Review from the Guidance Pod required as a follow-up. How we track changes in the guidance/code.

[ioanacontu]

Pierre, David E and Francis meeting this week or beginning of next week - discussion on the governance protocol/public API. A second round of review will follow-up - more people can get invited then.

[duboisp]

Me and @delisma have completed an initial review. The Public API initial draft was edited to take in consideration our initial/first review.

As next step:

• We would need to define and have a common understanding of what is a "component".
• Discuss each measurable elements of a component (referred as component composition in the draft) and complete the listing. For example, the "context of use" element could be valuable to be subdivided into "Component internal rules", "Where component can be used", "Supporting governance for the component"... Or renaming "schema" for "data layer"...

[duboisp]

Summary of Oct 4 tech sync:

(still an open discussion)

• Mention that we need to define and have a common understanding of what is a "component".
• Looking for a better name for "Component composition" which is used to name the group of a set of breakdown component element. Some proposition was: elements, layers, attributes, properties, sub-components.
• Sam will look to visualize the versioning (major vs minor vs minor).
• It was mention this document don't necessary need to be fully finalize at this point of time considering that we are early with the development of new solution/product issue from the GC Design System, like the design token. But it was mention this documents, at least early draft, is needed to ensure interoperability between solution/product.

[mcman12]

putting back in the backlog. Focusing the work on the proof of concept. We will revisit this work in the near future.