Design decision 14 - Semantic Versioning public API for wet-boew, GCWeb and GCWeb Jekyll

• Edit this page
• Revision history
• Questions or comments?

Summary

• Author: @duboisp
• Experts: @duboisp
• Status: Proposal Candidate
• Last updated: 2023-06-29
• History:
  • (2023-07-11) Addition of the following dimension
    • Basic HTML mode behaviour (testable)
    • Technical accessibility consideration (informational)
    • Other notable technical consideration (informational)
  • (2023-06-29) Editorial change and defined some new terms to help with measuring and documenting the API state
    • Renaming the defined “variant” for “change set”
    • Renaming “Function, callback and events” for “logic”
    • Term: variation, implementation, change set, iteration
  • (2023-02-11 to 2023-03-29) Editorial change, renaming “measure” for “dimension” and addition of the following dimension
    • Accessibility guidance
    • Pattern recognition
    • Out of scope changes
  • (2022-12-28) Splitting the following measurement:
    • Interaction pattern (ex. Functional event listing)
      • Essential component behaviour
      • Function, callback and events
    • Context of use (ex. Guidance)
      • Context of use
      • Guidance
  • (2022-12-28) Clarifying the archive pages are out of scope
  • (2022-11-15) Added distributed files in the versioning API, defining variants and additional edits
  • (2022-09-22) Clarified exception for some CSS class name programaticly used and expiration/removal of deprecated feature
  • (2022-06-29) Revised
  • (2022-06-23) Presented
  • (2022-06-22) Draft

The following is an updated and improved version of the Design Decision #3 about WET versioning API. It provides more details about what is versioned for the wet-boew product, GCWeb product and GCWeb Jekyll product.

The Semantic Versioning 2.0 is followed and applied.

Versioned product

Below are the items of our product that we are monitoring and illustrating changes via our version number.

WET-BOEW

• Product, excluding its deployment file structure
• Components

Dimension to measure:

• Component list
• Layout
• Style
• Semantic
• Logic
• Accessibility guidance
• Essential component behaviour
• Basic HTML mode behaviour
• Pattern recognition
• Context of use
• Configuration
• Static data value or its associated variable name
• Schema of the component variable data
• Technical accessibility consideration
• Other notable technical consideration
• Component dependencies
• Packaged files essentials and directly linked from pages

Always a patch:

• Sub-dependencies loaded via script, like data table and polyfills. That when our working example remain the same and our working example are not showing any new feature caused by that update.
• Provisional feature update

Identified as minor

• Provisional feature or provisional variation that are added or deprecated with a downgrade (functionality made available) in an external snippet

Excluded:

• Templates
• Site content including documentation and working example pages
• Components used for builing the binary
• Guidance of use
• External code snippet

Audience: Web author of the wet-boew product in a static server side environment.

GCWeb

• Product, excluding its deployment file structure
• Components
• Templates

Dimension to measure:

• Component list
• Layout
• Style
• Semantic
• Logic
• Accessibility guidance
• Essential component behaviour
• Basic HTML mode behaviour
• Pattern recognition
• Context of use
• Configuration
• Static data value or its associated variable name
• Schema of the component variable data
• Technical accessibility consideration
• Other notable technical consideration
• Component dependencies
• Packaged files essentials and directly linked from pages
• Change in the wet-boew dependencies components that require author to re-edit or provide new stable features for their page main content

Always a patch:

• Sub-dependencies loaded via script, like data table and polyfills. That when our working example remain the same and our working example are not showing any new feature caused by that update
• Provisional feature update
• Méli-mélo compilation (Its the product which would include any external code snippet)
• Thématique feature

Identified as minor

• Provisional feature or provisional variation that are added or deprecated with a downgrade (functionality made available) in an external snippet

Excluded:

• Guidance of use because this are managed by the Digital Transformation Office at Treasury Board Secretariat
• Site content including documentation and working example pages
• Components used for builing the binary

Templates:

• Fully in scope:
  • Baseline template and generic template
  • Widely used template
• Identified at most as a minor change with a breaking change when:
  • Moderately used and accompanied with an official communication out explicitly identified in the release notes
• Identified at most as a patch change with a breaking change when:
  • Limited use with all its active instances explicitly listed in its corresponding template documentation.

Where:

• Instance: Measured by the number of instances found on Canada.ca and by feedback received.
• Widely: There is more than 500 instance or reported widely used by various departments.
• Moderated: There is less than 750 instance or changes on Canada.ca are fully managed and applied by Principal Publisher.
• Limited: There is a few instance which are all explicitly listed in its corresponding template documentation.

Audience: Web author creating pages with the GCWeb product in a static server side environment.

GCWeb Jekyll

• Product

Dimension to measure:

• List of includes and its purpose
• List of layout and its purpose
• Front-matter configuration
• Site core configuration
• Jekyll component configuration
• Change in component that require author to re-edit or provide new stable features for their page main content

Audience: Web author that create pages with the GCWeb Jekyll theme.

Feature removal (Deprecation and backward compatibility)

Deprecated feature/code will last or remain functional for at least one (1) year from when it was formally deprecated. It might not render exactly the same but an equivalent version would remain functional. After that period, its removal would be identified by a major version as specified by the semantic versioning API.

For example, site that was using GCWeb (before v5.0) with the pre-2019 mega menu + breadcrumbs and haven’t changed their HTML markup was compatible with GCWeb until version v11.0.0 which was released on May 2022.

Documentation of deprecated component/feature

Scope: Components and features that has been deprecated from the component perspective but need to remain there for backward compatibility.

Its documentation are removed from a component perspective. That documentation would remain available from a product perspective moved outside the component. However, the backward compatibility code and generic/common deprecated working example will remain inside the component folder for quality control until the formal removal of the deprecated feature through a major version of the product is completed.

Formal removal

For feature/component that have been stale for at least one year from when it was deprecated from a product release.

The following steps must have been completed, documented and published.

• Search on Canada.ca active pages (excluding archived pages) to detect if the pattern or the deprecated code are still in use.
  • When instances are found:
    • A communication is completed with the affected client and we let a reasonable time to mitigate the required changes if justified.
  • When no instance are found:
    • Proceed with the removal if the other condition are met
• Mention the feature removal into at least two (2) WET monthly meeting where it’s corresponding meeting notes has been published live for at least 30 days.
• Removal can only be completed after one (1) year of when it was identified deprecated in a product release.

Dimension

An aspect of the component on which measures its compatibility impact for authors, implementers and users. Their measurement set the baseline to identify the impact of a subsequent changes applied according to semantic versioning 2.0.0. Each product have their own list of applicable dimension which are defined in the previous section and each component could refine what is in scope/out of scope, refine its measures and redefine what is observable.

Layout (ex. Wireframe)

Defined by how the semantic or inner component are organized among others within a component. Multiple layout can be supported for the same component. A layout can contain sub-layout which its own set of configuration.

• 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 is added.
• Patch layout change: N/A

Example with WET-BOEW and 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 is added.
• Patch: A reorganization that can be applied without changing anything exception of implementing (installing) the updated library. Like when the changes is fully managed by the javascript library.

Example of observable:

• Wireframe, a picture representing the component section and their placement
• Rendered HTML that leverage a CSS positioning mechanism (ex. grid system)
• The exact disposition are out of scope.

Style (ex. CSS):

Define the visual aesthetic of a component.

• Major style change: Significant 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.

Example with WET-BOEW and 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 to be used by an author.
• 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. CSS change (style and class name) that was designed for and only used programaticaly.

Example of observable:

• CSS class name and SASS rules. (Only the ones that was designed to be use by an author to customize the component.)
• 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

Example with WET-BOEW and 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 observable:

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

Logic

Define the component logic programmed in JavaScript which can be leveraged for an integration with a third party software. Function in scope are the one which are public or available through a global object which are out of scope of the framework internal. Callback in scope are the one used by public function or set through global variable that are outside the scope of the framework internal. Events in scope are the ones where a third party software we can bind/trigger through the DOM or via jQuery events handler.

• Major change: Removal of an public function, callback or events or major remodel of existing function, callback or events that require users to review how the component is used by their third party software.
• Minor change: Addition of an public function, callback or events.
• Patch change: Bug fixing or improvement of the code executed behind the function, callback and events.

Example with WET-BOEW and GCWeb:

• Major: Removal of function that require an update the corresponding HTML markup because the binding will be broken.
• Minor: Addition of a new jQuery event or addition of a new parameter in a function/callback
• Patch: Code update made inside a function or an event.

Example of observable:

• Public function name with its parameter list + type
• Callback signature with its parameter list + type
• Event name with its custom parameter list + type if any
• Signature of a function exposed externally through the wb global object

Pattern recognition

Evaluate from an user perspective if a change are going to require them some effort to keep it operable and understandable as it was prior the change.

• Major change: The change are perturbing which compromise how to use or operate the component compared as prior. Could require the user to learn new design pattern experience which are incompatible how it was before. Could represent a change (visual, structural, operational) which are perceptible in a way it could considerably impact the task completion rate in the context of where the component is used.
• Minor change: The change are noticeable and complement, add to the user experience and remain at least understandable as it was prior.
• Patch change: The change are barely be visually noticeable, don’t change considerably how to use or operate the component and remain understandable as it was prior. Or the change is an alignment with the ARIA Authoring Practices Guide or an alignment with an official W3C design pattern.

Example with WET-BOEW and GCWeb:

• Major: The visual change are deprecated and be replaced by a new revisited design pattern
• Minor: An operable function through a new button is added to a component
• Patch: A breadcrumb decorative separator is replaced by a different visual decorative separator.

Essential component behaviour

Behaviour and interaction, that if removed, could change the meaning of the component and/or impact implementer/author to apply an adaptation to their existing content build with that component.

• Major change: Removal of an essential behaviour and interaction. Or major remodel of an existing behaviour/interaction that require users to review how the component is used in their content.
• Minor change: Addition of an essential behaviour or interaction
• Patch change: Refining an essential behaviour or interaction definition or remodel of an existing behaviour without requiring any users intervention neither changing the meaning of the component.

Example with WET-BOEW and GCWeb:

• Major: Removal of an essential behaviour that require an update the corresponding HTML markup, like removing an HTML button “Pause” on a carousel.
• Minor: Formal identification of an behaviour as being essential.
• Patch: Refining or/and clarifying the scope and the output of an existing identified essential behaviour.

Example of observable:

• List of essential behaviours along with a definition and example is any

Basic HTML mode behaviour

Description of any special behaviour that are testable of the component which can, should and must be followed when the page is navigated in basic HTML mode.

This dimension are testable only and allow to test the integrity of the component and any change made on this dimension are not going to impact the component versioning API.

When described basic HTML behaviour must be followed, then it must be duplicated in the measured dimension “Essential component behaviour” to ensure that any change to it are captured according to this public versioning API.

The versioning API aspect of this dimension are monitored through the other measured dimension such a change made to: Style, Semantic, Essential component behaviour, Logic.

Accessibility guidance

List of rules which much be applied and followed in order to ensure the component is used in

• Major change: Removal or addition of a guidance where the author must review their page to apply a fix or to validate if the component are still conform.
• Minor change: Removal or addition of a guidance that don’t impact the previous accessibility conformance state of the component. The author could revisit their page but its for optimisation purpose.
• Patch change: A rewording of a guidance which don’t change its meaning. The removal of a guidance which don’t require any action and none can be taken by the author based on that removal.

Example of observable:

• List of accessibility guidance rule/steps.

Guidance of use

Define how a component should be use, when and where to ensure it is used/presented uniformly through the organization. Excluding any guidance required to ensure the component are used in an accessible way. This dimension is out of scope for WET-BOEW, GCWeb and GCWeb-jekyll.

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

Example with WET-BOEW and GCWeb:

• Major: Not applicable but it might imply a change in the configuration and/or in the essential component behaviour.
• Minor: Not applicable but it might imply a change in the configuration and/or in the essential component behaviour.
• Patch: Not applicable but it might imply a change in the configuration and/or in the essential component behaviour.

Example of observable:

• Documentation about its purpose and when to use.

Context of use:

Define where the component can be used in the page code or in a special context.

• Major change: Addition of a context restriction that is narrower of it’s preceding definition.
• Minor change: Removal of a context restriction to be more generic or the addition of an new context where the component can be used
• Patch change: Clarification of an existing context of use without requiring the intervention of the user to rethink their published work.

Example with WET-BOEW and GCWeb:

• Major: Restricting a component to be used inside another component like a in a 8 column wide (medium) which was before allowed to be used as direct children of the main element. This change do require the author to revisit their current instance and make updates.
• Minor: A component which was restricted to be used in a column component can not be used in as a direct children of the main element.
• Patch: Clarification of how a context are explained for a component.

Example of observable:

• Definition of the context of use for the component, like by making an association with those category:
  • Template head (ex. breadcrumb)
  • Template footer (ex. contact us link)
  • Content area (ex. alert component)
  • Global and site wide (ex. proximity styling)
  • Limited to single full page (ex. splash page)
• Component to be used in page header or page footer or in main page area.
• Component documented and defined inside the “/sites/” folder in GCWeb have a context of use limited to the global page or page header or page footer or commonly used across multiple pages like date modified which are located in the footer of the main content area.
• Component documented and defined inside the “/components/” folder in GCWeb have a context of use with a baseline to the main content area.
• CSS selector that identify the context of use.
• Description of the context, like footnote component is limited to any content in the main element.

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.

Example with WET-BOEW and 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 observable:

• 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. Often those static string can only be defined during the implementation phase and not during the authoring phase. If those need to be updated during the authoring phase, we will most likely have a corresponding configuration or/and schema to achieve the expected result. This also define the string that can be added by author but with a clear design intention to have it immutable for a specific language.

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

Example with WET-BOEW and 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 observable:

• 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. This is a mapping defining how to interpret data that can be provided by the author through the HTML code or via another data source like a JSON file/API call.

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

Example with WET-BOEW and 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 observable:

• Shape graph
• List of variable

Technical accessibility consideration

This is an informational measured dimension to facilitate the code maintainability.

This dimension measure are quickly describing, with a reference to any research if possible, why this component are designed in a specific way to meet and/or enhance accessibility conformance. It is intended that any WAI-ARIA advance feature used by the component logic, semantic or recommended by the accessibility guidance must be noted under this dimension along with a quick rational of why it is/should be used.

The versioning API aspect of this dimension are monitored through the other measured dimension such a change made to: Style, Semantic, Logic, Accessibility guidance.

Other notable technical consideration

This is an informational measured dimension to facilitate the code maintainability.

This dimension measure are quickly describing, with a reference to any research if possible, why this component are designed in a specific technical notable way excluding the accessibility consideration aspect.

Any accessibility related technical consideration must be measured and recorded under the dimension “Technical accessibility consideration” and not duplicated here.

The versioning API aspect of this dimension are monitored through the other measured dimension such a change made to: Style, Semantic, Logic, Accessibility guidance.

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.

Example with WET-BOEW and GCWeb:

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

Example of observable:

• List of major versioned component

Packaged files essentials and directly linked from pages

Measured as if an implementer deploy and rewrite the distributed packages, would he need to update some of their published web pages to support that new deployment.

• Major change: Removal of a files identified or previously identified essentials and that are directly linked from a page
• Minor change: Addition of a new file that is going to be identified essentials and be directly linked from a page.
• Patch change: Update of an existing essential files or when a changes occurs in the others files contained that are indirectly linked, like via script or CSS.

Example with WET-BOEW and GCWeb:

• Major: Removal of wet-boew.min.js linked by every pages
• Minor: Addition of an essential decorative common image on a template or used by a component
• Patch: Update of an existing essential file like theme.min.css or/and sub-dependencies loaded by modernizer like datatable.net

Example of observable:

• Files and folder structure of the distribution packaged in a zip file attached to the release.

Out of scope (Always a patch)

The following items which are changes that is happening in the same repository but don’t impact the component definion itseft or in a negligable way which are not perceptible from the working example according to a quick impact check based on the versioning API.

• Build: Dependencies or script used for helping the developing environment and/or used to compile and/or used to test the product. For example the dependencies listed in the “devDepencies” package.json file, the Gruntfile.coffee, Pupetters with mocha test, Docker, installation script.
• Test: Any test script or configuration used for testing of the product or a component of the product.
• Content: Web pages and contained text which are surronding the component working example. Working example addition of already supported use case.
• Repository: Organisation of the source code file with their name and including any assets as long their change/move/deletion/addition don’t impact the released product according to the dimension “Packaged files essentials and directly linkeded from pages”.

Terms used in documenting the component

The following are term used to document how this public versioning API are measured and impact a specific component.

Informal: Variation and implementation are informal and any change to them are out of scope to define the version of a component Formal: Change set and iteration are formal and any change to them might have impact on defining the version of a component.

Variation

A variation is a named configuration based on change set which define a measured component. It’s intended audience are for implementer and author that are going to use the component. A variation is not formally versioned. It may contains some history notes and it must indicate on which iteration it was based on. A variation can include multiple implementation to help implementer and author to implement the variation in their site or page.

Implementation

An implementation is an instruction set, code sample, code diff, screen capture, examples… that guide the implementer and the author to leverage a variation in their site or page. Each implementation must indicate on which iteration is was based on. An implementation is not formally versioned. The same implementation can be use in multiple variations as appropriate.

Iteration

An iteration is a change description that has occurred in the component. It specify how that iteration is detectable and distinctive from the predecessor iteration. It describe the API dimension along with a changes description that occurred. An iteration must contain an observed date or a creation date to define when it was captured and documented. The iteration tree is a detailed version of the change history of the component from its public versioning API view.

Change set

A change set is a measured component from its various public API versioning dimension. It is based on an iteration. The change set is formally what is used to determine the version of the component. The removal of a change set will result in a major change for the component and the addition of a subsequent change set will result in a minor change for the component. If the base iteration of a change set is updated, the change described by the iteration would impact the version of the component. Only the change set is considered and monitored. Unless specified, the public versioning API dimension are strictly limited the description and measure attached with the change set. Anything that are omitted or not identified must be considered out of scope. A change set can be seen as a branching pointer into the component iteration tree.

A change set will contains minimally the folowing information:

• Name: Human readable short name that make the change set distinctive among other change set name and the removed/deprecated change set.
• Iteration number: A reference to the iteration this change set is based on.
• Dimension description: A description that describe how we can measure or the actual measure of every applicable API versioning dimension.
• Status: The type of change set which define its influence on the component version.

Type of change set

Change set must define a type which is also representing its current status.

There is four (4) type of change set:

• Stable: A supported component change set
  • Version API impact for the component:
    • Major: The change set is deprecated or removed
    • Minor: The change set is newly added
    • Patch: The change set is updated
• Provisional: Experimental feature in a good standing to be stabilized
  • Version API impact for the component:
    • Major: Not applicable
    • Minor: The provisional change set is added or officially deprecated with a downgraded (functionality made available) in an external snippet.
    • Patch: The provisional change set is updated or removed after it’s official deprecation.
• Informational: Change set where it’s structure is mostly managed by other factor like JS. For example the enhanced interface of a carousel component.
  • Version API impact for the component:
    • Major: Not applicable
    • Minor: Not applicable
    • Patch: The informational change set is updated or removed
• Deprecated
  • Version API impact for the component:
    • Major: A stable change set is deprecated or removed.
    • Minor: A provisional change set is deprecated with a downgraded (functionality made available) in an external snippet
    • Patch: A provisional change set is removed. Or an informational variant is deprecated or removed
  • Version API impact for the product:
    • Major: When the backward compatible code of a change set is fully removed
    • Minor: When a new change set is added
    • Patch: The change set pattern is updated or review.