update all components to brand-context -v 31.0.1

[Sreilys]

update all components package.json to brand-context -v 31.0.1

[sturobson]

Hey @Sreilys - thanks for this!

We would also need to update the component version number at the same time so that it gets updated when folks install the components in their projects.

The question would be if it's a major(X.x.x) or minor(x.X.x) release for each component. As these would be visual changes that don't effect the implemented HTML in a project I would think a minor release would suit it best.

Semantic versioning is a great thing, but for Design Systems style changes it can feel a little unclear as to which type of version change to use when you've made a font a little larger, or changed a border colour.

Pinging @alexkilgour for suggestions on which type to use here? One last major version of the monorepo components before the move to single release?

We would also need to update the history.md file for each component this affects too.

🙏🖤

[alexkilgour]

One last major version of the monorepo components before the move to single release?
Hope so @sturobson !

[alexkilgour]

The major/minor thing is interesting. In most of these cases you would be inclined to think that they are minor, but it's slightly complicated by the fact that we have that link to the brand context, which is an indication that "to use this version of the component you should be using this version of the brand context" - but it is entirely down to the consuming application to make sure that is the case (as an aside this isn't really happening, which is one of the reasons for looking at the single release, but that is another story!)

Seeing as we use the carat (^) to define dependencies in most cases, this means that the deps are updated to the latest possible minor/patch update upon installation. So if we have a component that is changing from 3.0.0 to 3.1.0 and that change updates the brand context version, we could be in a scenario where someone does not update their dependency to 3.1.0 but they get it anyway (because it is defined as ^3.0.0). This change might require something from that context version, but the consumer has not explicitly updated their context version (or tested other components with it)

Which all means, I think that these need to be breaking changes.

This is a annoyance that will go away with the single release and make your lives easier!

[alexkilgour]

I also think that as in most cases we are updating multiple breaking changes of the context, we need to

1. Check that the components still compile (run the demo script for that component) in case some variable has changed or been removed for example
2. Visually check the components to make sure they render correctly

I realise this is a bit of a time-consuming task! But I did build a small tool to make this easier.

This allows you to compare the changes you have made on your branch (in this case a new context version) to the last version of a component. To use it, make sure that you have run the demo command for the component to generate the static demo in the demo folder, then run the npx command specifying the last working version of the component. This will spin up a local server that display the two versions side by side. You should be able to see that there are either no visual regressions, or at least the visual changes are expected (spacing changes or font size changes for example, that filter down from the brand context)

[sturobson]

Thanks for the feedback and interesting information betwixt hypothetical implementation (hopes) and real world usage.

Which all means, I think that these need to be breaking changes.

From that I agree - we should move each component to a major breaking change (X.x.x) instead of the minor change we initially decided on (x.X.x).

Along with this we need to work on communicating what we're doing here and what the future looks likely to be (I've started and I'm working on a 'single release' document explaining (as I see it) all the ins and outs of 'the future' (I'll share it soon)).

@Sreilys can you go back in and change the version in the package json and the versions in the history to match major (X.x.x) bumps

[sturobson]

I also think that as in most cases we are updating multiple breaking changes of the context, we need to

• Check that the components still compile (run the demo script for that component) in case some variable has changed or been removed for example
• Visually check the components to make sure they render correctly

Agreed, I'll rewrite the initial issue to be follow the what/why/done when we've been using for Elements and include these.

I realise this is a bit of a time-consuming task! But I did build a small tool to make this easier.

Would it be good to jump on a call w/ @Sreilys to go over this?

This allows you to compare the changes you have made on your branch (in this case a new context version) to the last version of a component.

I'm thinking on how we can 'easily' introduce something like BackstopJS (I think I've seen it in use at SN somewhere already (and I've used it on my last two contracts) to help do some automated visual regression testing too.

[sturobson]

on a broader note of 'what is a patch/minor/major change' and how do we denote if a component is 'stable' or 'experimental' etc. We have a ticket on the project board to work through this and create or update the definitions and expectations.

Personally I've always found 'style changes' being a breaking change a weird one if the underlying HTML doesn't change and the content is still available on the web page.

Current SemVer definitions in Design Systems are a 'little bit sticky' (as one of the comedians would say on No More Jockeys

[Sreilys]

Thank you @alexkilgour for the very interesting feedback and explanation. And thank you @sturobson for the great support.
I will change the versions as Major change in package.json and History files, and then run the demo and test the diff with the tool suggested.

[alexkilgour]

Big yes to visual regression testing at some point! The tool was really just a quick stop gap 😃
I know there is a lot going on for Elements so this maybe is top priority right now

[alexkilgour]

Personally I've always found 'style changes' being a breaking change a weird one if the underlying HTML doesn't change and the content is still available on the web page.

Yep, agreed. And not to keep banging the same drum, but this does become clearer when everything is versioned as one! But agree the definitions do need work for the single release, the current definitions are mostly to mitigate this slightly odd brand context dependency situation

[sturobson]

I've updated the 'todo list' in the original issue this comes from.

aside: this has me thinking about the slight disconnect there is from write the done when todo list in the issue and it not being easily visible in the PR … but I'm not sure how that could be easily solved (apart from copying and pasting it (which could be a problem if it gets updated in the issue (like I just have done) and not the PR)).

[Sreilys]

Aligned the pr with according issue todo list.
One problem occurs, for few toolkits, when I try to test the new demo file against the existing version of a toolkit with the utility-diff tool, as it does not show the visual component.
toolkits that don't show any visual in the diff tool are: Global-forms, Global-customer-satisfaction-input, Nature-header, Nature-hero.

[Sreilys]

@alexkilgour after some digging, imo the problem with the diff-utility that does not show the view, is somewhere in the css.
I've tested stuff around and I got 2 issues that, if removed, make stuff work as expected.

1. this css comment: intentionally avoids 'max' and 'range' to prevent bloat. html-minifier (used by the diff-tool) has a removeComments option, but docs says it only works for html, not css. The single quotes in this case are the issue. (I can make a pr that removes the quotes as a simple solution).
2. Data URIs: inspecting nature-header, we have a .c-header__select that has a background-image with data-uri and if I remove it, all works good. I can see the component preview.

We would need to think about a solution for that. Also I am now wondering if we should move this discussion out of this pr. Open to suggestions :)

[alexkilgour]

brand context needs to update here

[Sreilys]

Info: @alexkilgour suggested to NOT update global-customer-satisfaction-input for now.
"This component has a specific backend, so in order to update they also need to update that BE and the BE tests. This is the first of a new type of component - you may have seen in the elements site, called widgets at the moment".
A new pr in the future will be made to update that specific toolkit.

[alexkilgour]

Looking good!