RFC: Breaking changes and release workflow in Kendo Themes

[silviyaboteva]

The motivation

The several discussions around the latest Chip and Tabstrip rendering changes. I synced with @Xizario and the @telerik/kendo-react-team and we decide to open a new discussion where we will list the most common changes we make. We will also propose the difference between breaking and non-breaking change, what should the commit message consists of, and the release workflow.

The result

The output we want to achieve is to have a clear structured document in our WIki where we can refer when making changes in the themes.
Our support engineers can use this document as an official statement when clients asks "Why this is not marked as a breaking change?"

Most common scenarios in themes

Let's say that we have a task to update the X component and we have a new design already done by our design team.

1. The change can be implemented without any rendering changes (either markup or class names).
   Changes: This case is the easiest one as there will be changes only in the SCSS files. It won't require sync with the suites to update anything in the component.
   Is this a breaking change: In this case, we assume that it is not a breaking change.
   Commit message: We can push the changes with the following commit message: feat(X): update component styles based on the latest design.
   Release Workflow: As this is not a breaking change, we can safely release it with a minor version.

Disclaimer: This might be a breaking change for Unite UX and clients that have visual tests in their applications.

2. The change requires adding a new HTML element or a class.
   Changes: The changes will be listed in the PR/public issue with the new rendering output. It will require sync with the suites to update the component.
   Is this a breaking change: In this case, we assume that it is not a breaking change. As the markup has only additions to it, without any removed content.
   Commit message: We can push the changes with the following commit message: feat(X): update component rendering and styles based on the latest design.
   Release Workflow: As this is not a breaking change, we can safely release it with a minor version.

Disclaimer: This might be a breaking change for clients that have custom CSS with selectors getting direct children. For example: .k-test > .k-test-child. If we add a new element to the rendering, the selector might become invalid.

3. The change requires modifying/removing an existing class or an HTML element.
   Changes: The changes will be listed in the PR/public issue with the new rendering output. It will require sync with the suites to update the component.
   Is this a breaking change: TBD
   Commit message: We can push the changes with the following commit message: TBD
   Release Workflow: TBD

Disclaimer: TBD

4. The change requires modifying the SCSS variables' names.
   Changes: The changes will be listed in the PR/public issue with the new names. It won't require sync with the suites to update the component.
   Is this a breaking change: Yes.
   Commit message: We can push the changes with the following commit message:

fix(X): update X module scss variables

BREAKING CHANGE: Update X module scss variables

Release Workflow: As this is a breaking change, we should bump a master version. In case the change is not critical, we can create a branch, v6 or vNext or whatever, and push the changes there. Once we have a solid amount of changes, we can plan when to release the major version.

Disclaimer: The breaking change for clients is when they customize their apps via SCSS variables. The variable becomes invalid and they will have to go and check the new changes.

5. Other?

Any feedback/opinion will be highly appreciated!

cc/ @telerik/web-components-and-tools

[Xizario]

The design changes are indeed driving factor for changes in the themes, but there are other changes like fixes and implementation improvements that are not design driven. Should we list such examples in point 5, or remove the "new design requires" part from points 1-4.

[silviyaboteva]

I agree! Updated the new design requires -> change requires

[Stamo-Gochev]

Points 1, 2, and 4 look as good suggestions to me, I suppose that the 3rd case has the potential to be the most debated topic:

The change requires modifying/removing an existing class or an HTML element.

which is probably what we want to reduce as much as possible, so what about listing some exceptions/references (if any apply) to the listed scenarios based on our experience?

For example, using some pull requests from the past that resulted in long discussions, we can provide more clarity for the general case and list specific scenarios that might look like a breaking change at first glance, but are actually not (or vice versa). Considering some concrete examples now can help us come up with a good decision as the definitions might be too abstract for making a solid decision right away. Otherwise, it sounds to me that the general decision is "yes, this is a breaking change".

---

Note: The writings below might not have a big of an impact at all when considered for the themes, but I am posting them anyway as some reflections on our experience when tracking the breaking changes in the .NET ecosystem.

On a side note, we can brainstorm about taking some ideas from the .NET world around the different types of breaking changes. I haven't verified with any dataset if there is an actual issue for users of the themes to read the release notes and understand if the listed breaking change is affecting them or not, but I suppose there are cases, where some would want to do so as this will give them more information on what effort will it take for them to upgrade to a new version.

For example, the .NET article lists source breaking changes:

a source breaking change doesn't affect program execution but will cause compilation errors

Making a contrived analogy with the themes - an update might not result in any problems if using the new version of the theme by an already compiled file, but if you want to compile it, then you will get some errors.

As the themes are used by multiple "types of personas" now, we might consider not only marking something as a breaking change but adding a "category", which explains the area this change affects. This might turn out to be helpful when the different types of clients are looking at the release notes as certain types of breaking changes might not affect them at all (thus they will not be that "scared" to update).

Using the analogy from .NET, here are some imaginary categories and their description of breaking changes:

• visual - when a change is made to a certain CSS rule and the final output might result in a mismatch when compared to the previous version (e.g. in a visual test). This is close to point 1 in the "Most common scenarios in themes" above. Note: There might be a need for a "special" category for Unite UX (even an internal one in some way) or Unite UX might be affected in multiple ways
• source - using the analogy from .NET - if you use the already compiled theme right away, you will not notice any difference, but you will if you try to build it from the source code. Developers that do not work with the source of the themes will actually be unaffected by the "breaking change", while those who do will.
• rendering - the HTML or class of element(s) has changed - custom CSS that depends on selectors might stop working (point 3 from "Most common scenarios in themes")
• [... other categories]

The approach we currently depend on for generating release notes might not be suitable for such categorization though. As the themes repo is public, this might be better solved in another way, e.g. using a Breaking change label as well as another one like Breaking change: visual incompatibility. Using this from the .NET repo has helped us several times for the Telerik UI for Blazor suite.

[bergenhem]

I really like the idea of providing different categories of breaking changes. A comment I have received from our customers that have custom themes is that they pretty much have to just update and hope for the best when it comes to styling.

I think it would be great to come out and acknowledge that a breaking change is more than just something that breaks the app and give users a heads-up that changes have indeed occurred. We could also use this as a mechanism for users to filter down the changes in case they want to see all visual changes that have happened over the last few releases etc.

[tsvetomir]

1. The change can be implemented without any rendering changes (either markup or class names).
   Changes: This case is the easiest one as there will be changes only in the SCSS files. It won't require sync with the suites to update anything in the component.
   Is this a breaking change: In this case, we assume that it is not a breaking change.
   Disclaimer: This might be a breaking change for Unite UX and clients that have visual tests in their applications.

This interpretation is a bit narrow as the themes are not just an API. They are very much defined by their appearance. Changes to the appearance can be either:

• A fix—something looked broken before, but it now matches the design or expected behavior.
• A feature—an additive change that does not affect existing users.
• A breaking change—something looked differently before, but was otherwise working as expected. The majority of design changes will fall into this category.

It's important to differentiate and mark the breaking changes accordingly. Otherwise customers may be forced into a situation where they can't obtain an important fix because, as a bonus, the Grid is now purple 🍆 . Not that a purple Grid is bad, but it shouldn't change colors overnight.

[simonssspirit]

@silviyaboteva Thank you for starting this great discussion.

I love the idea of having different categories on the breaking changes. This will allow customers to easily find what is changed and how it affects them. Nobody likes breaking changes, but if they are defined and explained well, it will be easier for everyone, and customers will feel more confident updating.

I agree with points 2 and 4.

• Point 1 The change can be implemented without any rendering changes (either markup or class names) This is an interesting one for me because making component X from blue to pink is one change and making the Grid cell padding from 16 to 17px is another. Both will lead to errors in the visual tests, but at this point, every change in the theme will lead to such errors, so for me, this is not a leading factor. The important change for me from this category is the color one as it may lead to back color combination in the customer application and even make some parts of the application unreadable. For me, changes in the component colors should be considered a breaking change,

• Point 3 The change requires modifying/removing an existing class or an HTML element. For me most of these changes maybe with some specific exceptions have to be considered a breaking change for two main reasons:

  1. Removing a class name can break CSS selectors that customers use to style their applications. This may not be the best way to use the styling, but we live in a not ideal world and people sometimes make implementations that are faster. Also, many of the styling solutions we are providing in the tickets depend on these classes.
  2. Removing a class name can also cause issues for customers using the querySelector method or jQuery selectors in general which is very common even in some React and Angular applications. Removing a class will cause those methods to return null which will lead to a JS error and will break the application.