Design decision 3 - WET API/Blueprint

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

Summary

• Expert: @duboisp
• Status: Approved
• Type: Refine current interpretation
• Last updated: 2018-05-17
• History:
  • (2018-05-17) Approved at the WET roadmap meeting
  • (2018-04-19) Presented at the WET roadmap meeting
  • (2018-04-18) Initial draft

Issue

There is no or only a vague guidance on how versioning should be applied. There is no official information defining how an element or a function in the WET core or in a WET feature should be evaluated in order know the actual changes introduced by a PR (pull request) would have a major, minor, trivial impact on the feature and the project overhaul.

The current versioning convention used in WET are not very helpful other than being sequential. Some trivial/patch release also introduce some non-documented breaking change.

Propose solution

Use semantic versioning 2.0 for WET. However in order to following it, it require to define what we consider to be the API of our product.

A WET feature has multiple facet/component which is not limited to the API (Application Programming Interface). The design pattern specified by the plugin, the layout, how it can be configured should be an integral part of the WET feature versioning. All those multiple versioned facet are defined as the WET feature blueprint.

When the terminology “WET feature blueprint” is interpreted against the semantic versioning 2.0, it represent the same as the “public API”.

Blueprint need to be documented and monitored. A non official documented blueprint for a given WET release are considered out of scope and should be considered like an experimental feature that is at risk to change.

A working example aren’t implicitly part of the blueprint of a WET feature.

WET feature blueprint

The following are the blueprint component for a given WET feature:

• Function: Description of the plugin interaction such as events, executing action, callback.
• Configuration: Description of how to set behaviour and/or output. Usually done through sending parameter, like in JSON format so the data in his JSON form are part of the blueprint. It’s variation are also part of the blueprint, like CSS class use as configuration, the use of custom data-* attribute,…
• User interface: Define the HTML markup and semantic required by enhanced interface and basic interface. It includes variation of enhanced interface when supported configuration is applied on the feature.
• Data source: It represent an abstraction layer of the contextualized information gathered from the basic HTML interface. Also for each external data source, it define the structure of the information required for the WET feature.
• View and style: Presentation layer of the information on how it is visually structured and styled through an combination of user interface and configuration. Often the presentation would be presented as wireframe accompanied with a few design notes.
• i18n string: List of translation string used by the feature.

For one WET feature, multiple variation may exist for one blueprint component.

Next step

• Present this note at the WET roadmap meeting
• Design a documentation skeleton for the blueprint.
• Use this interpretation for the design of WET 5 and to resolve issue relatively to Basic HTML mode.