How to version UI components

[dkrikun]

Hello,

I have a project setup which is a web-application, it has client and server sides. I would like to use semver to version both of the sides. Semver says, I need to define an api formally, which is rather straightforward for the server-side, but for the client-side it is somewhat unclear how to do this, because it is mainly a UI module.
I understand that semver was created w/ package managers and automatic dependencies in mind, however, because I would like to use it project-wide for versioning, I would like to suggest how to treat UI as an artifact w/ api:

Patch version Z (x.y.Z | x > 0) MUST be incremented if only non-functional ui elements have been changed, i.e. font, color, style changes. Insignificant layout changes also count, however, major layout changes are indeed functional and thus require major version change.
Minor version Y (x.Y.z | x > 0) MUST be incremented if something new has been added, however, previous functionality is fully present.
Major version X (X.y.z | X > 0) MUST be incremented if any functional ui elements have been changed or removed, i.e. layout rebuilt, buttons removed, meaning of some ui action has changed.

Ideas?

[bessarabov]

My idea.

Patch level changes only when there is some changes that does not change the way the web page looks and works. It can be some internal refactoring or js/css minification. The patch level also include bug fixes.

For the Minor I completely agree with you idea. But from my point of view Minor level change should also include font/color/style changes that changes the view of the page.

For the Major level I also agree with your idea with small addition. Major level MUST be changed if there is backward incompatible change of the page DOM. To check if it is backward compatible one can imagine some DOM parser that works with that page. If the DOM paser must be changed to work with the new version of DOM then it is backward incompatible change and the Major level should be updated, otherwise it is Minor change.

[franciscop]

I'm the developer of Picnic CSS and I'm also having some trouble defining what semver is when we talk about a CSS library. Even more now that the library itself is composed of versioned plugins. While I try to do my best, I haven't been able to follow semver. However this is how I interpret it for Picnic:

• Major: A change that requires the DOM to be changed to keep working is a major change. The documentation also needs to be changed to reflect this. This includes but is no limited to class name changes and DOM dependencies changes. One example of this is when the class .toggle needed to be added to the hidden <input> instead of in the wrapper element.
• Minor: When a new feature is added that doesn't require a DOM change. However care must be taken, since this might imply that a class name is added that breaks in your specific code if you were using the same class name. One example is when I added the .pseudo class to the button plugin.
• Patch: Something that is broken in a browser gets fixed to follow other browsers and the documentation. Note that this might still break your code since you might have created your own workaround for this particular problem.

In general I find that semver is not so suitable for any language where there's no private state. When there's only public state, any small or big change becomes a potential compatibility breaker. This should affect even more any JSON API out there for example, where just the change of a key can become a deal breaker.

[EddieGarmon]

The intention of SemVer is to allow DOWNSTREAM API consumers to become consistently informed with respect to handling updates to dependent libraries, without breaking their code.

That said, for end user versions (no one depends on you) do what feels good.

If your UI components provide an API for consumers, please follow the existing semantics. Visuals, imho, should be managed independent of any API.

[jwdonahue]

@dkrikun, unless you need further clarification, please close this issue at your earliest possible convenience.

[worc]

over the last few years, i have yet to find a good use-case for semver for end-user applications / ui components. and it's a constant question in the back of my mind when putting together a node/npm project and npm init generates a version number. generally, it's probably okay to remove that version field and forget about trying to shoehorn your project's changes into semver.

using calver in a changelog is probably the more appropriate versioning system for your end-users in that case. it's something you see in app store release notes, "new feature" blog posts for web-based tools, and even IDEs tend to use calendar time of some kind to mark releases.

[ljharb]

We version them constantly and rigidly adhere to semver, and it's very helpful. UI components take input (props in React, eg) and that's an API whose changes need describing. Using prose is always good but relying on prose, when it's possible not to, is not a good idea at all.

[worc]

@ljharb sure, but what about the output? what's the difference between a backwards-compatible and backwards-incompatible change? is accessibility enhancement a bugfix or is it better considered a backwards-compatible feature? what about automation testing hooks? what about removing those hooks?

there's a lot of bike-shedding that goes into just defining what types of changes fall into MAJOR.MINOR.PATCH and it just seems wiser to avoid the conversation entirely. i don't doubt there are definite use-case for UI and semver, but i haven't come across them personally. and i wanted to reemphasize the older conversations here that, even now, with semver well-established, it's still a struggle to shoehorn it into a end-user applications and other UI-centric projects.

the problem comes from trying to use a versioning scheme meant for Application Programming Interfaces with programs that are largely or solely User Interfaces. people aren't the same as machines, and a semver number isn't going to guarantee Program-to-User compatibility.

[ljharb]

That there’s bikeshedding does not mean the version number has no value, it just means that for some projects, some consensus may have to be reached about what the public API exactly is.

[eps1lon]

This is heavily dependent on the specific implementation details. For UI libraries that target the DOM every slight change in the CSS might be considered a breaking change. You can be very rigid here and consider the actual CSS part of your public API. You could also define the look (i.e. every pixel) of your UI components in an arbitrary container as your public API.

Accessibility is a hard topic since most implementations you see in the wild vary quite a bit. If you say follow WAI-ARIA Authoring Practices 1.1 then any change is a fix. Remember just because some usage of your library breaks doesn't mean it's a SemVer breakage.

If you remove attributes from your DOM nodes then that's only a breaking change if they are part of your public API (e.g. data-* attributes).

[worc]

i don't disagree with the usefulness or the value in semver if your users understand what it means. but i still don't see a strong argument here for semver for end-users. a project bottom of the stream, with end-users as its primary audience, is probably going find semver lacking as a tool for communication.

[ljharb]

It depends on who you mean by “end”. The users of a website don’t care about semver, but the creator of that website definitely cares about the semver of every component, UI or otherwise.

[worc]

why does it depend? i just defined it. end-users aren't getting any value out of semver, because they aren't going to be speaking that language.

[ljharb]

@worc end users (if you mean, the non-developer humans using the product) absolutely get value out of semver, because it helps the end-users (the developer humans using the packages) ensure that the product isn't broken. You get significant value from automotive parts standards even though you're not a mechanic, because it keeps your car working.

[worc]

that's a really bad analogy. car parts don't go through versions, not the same way software does. you use specific, static part numbers to identify what you're looking for, not one that dynamically updates over the years. and if you are concerned about finding the right version of a part--like if you're going to a pick and pull--you're not using semver, you're using years and generations to differentiate cars.

semver doesn't have any meaning to an end-user.

that's why it's such a struggle to make semver work in those situations. and why over the last few years you see timestamps and variations of calver or big version numbers going out to end users. and it's why this old thread was ever opened in the first place, semver is a bad fit for end-users.

[ljharb]

Right but semver on the UI components is still valuable to everyone, because the app devs can use that info to keep the app working for end users. I’d agree a semver on the app itself may not provide the same value to end users, but that’s not what this thread is about.