The Australian Government coat of Arms

Communities of practice

Communities of practice

Differences between version

#1

Hi,
I just found out that UI-Kit version 3 was released few days ago. What is the easiest way to see what has changed from previous version 2.0.3?

On npmjs.com I can see only there is new version, but not the differences.
On GitHub I can look for last commits, but I cannot tell to what version they belong.

Suggestion:
It will be great to use releases on GitHub in sync with NPM version. GitHub then automaticaly provides the list of commits from previous version.

#2

Hi @petrillek!

I agree that it is currently not the easiest to see new releases of the components. Here are a few things to consider about the current situation and some ideas on how we can adjust our workflow to better communicate to the community.

All of the components are individually versioned. We just updated A11y-Color and removed a property which meant that a new major version of core was required in case a user was already using that function as it would break. This meant we had to patch all the other versions of components ( these are not new major versions as the components themselves functionality did not change).

If we were to do releases on GithHb how would you want this to work? We don’t have a whole of design system components version as each of the packages are individually bundled and versioned.

We are currently trying our best to quickly iterate and make necessary updates while following strict semantic versioning. We will be always updating the individual components and their changelog / readme files and trying our best to communicate these with the community.

One idea may having a new community post with recent changes to components?

Would love to hear more opinions on this topic :slight_smile:

1 Like
#3

Thanks for the explanation @alex.page!
I agree it is hard to came up with a solution for this.

Here are few more opinions from me.

  1. Versioning
    Currently it is a little bit confusing as version number spans from 1.0.4 (Animate) up to 4.1.1 (Header), yet all are dependent on Core which is in version 3.0.0. Does it mean, that animate is old and outdated? Or Header has something extra.
    Can we have a system, where if Core is 3.0.0 all components will get updated to 3.. as well. Then they can live their own life, but only in minor versions.
    It will help to “market” the whole UI-Kit, as you can tell version 3 is released and all component will be in version 3.

  2. Documentation
    It will be nice to have a one UI-Kit changelog page with all the individual changelogs put together.
    Maybe in form of a timeline. Hopefully it will not slow the development down too much.

For example:

16 July 2018
Core – v3.0.0 - Binary search a11y color, replace node-sass with sass
Body – v2.0.7 - Replace node-sass with sass

25 May 2018
Body – v2.0.6 - Change npm run watch browser-sync location
CTA Link – v2.1.0 - Add support for react router
Buttons – v3.0.0 - Add react router support

Have a nice weekend. :wink:

1 Like
#4

Versioning
We use Semantic Versioning for each component. (Major.Minor.Patch)

Which provides more transparency for developers about what work is required to update than a single major version for all components:

  • Major Incompatible changes — Requires changes to implement, like updates to HTML, class names
  • Minor Backwards-compatible features — Features that don’t require much/or any implementation.
  • Patch backwards-compatible bug fix — Fixed something with doesn’t require implementation

We also want to step away from the whole “UI-Kit v3” concept and move to something more iterative. Where value is delivered more often in smaller pieces and teams can choose which updates to use, rather being required to update everything all at once.

As an example if Core gets a new Major version (incompatible changes) all components would be bumped up a Major version anyway because they have a dependency on it and some effort would be required to update.

So in direct answer to your question: If we have Animate.1.0.4 and Header.4.1.1, and both are the latest version; then neither of them are ‘out-of-date’… If we then discovered an accessibility bug in Header which requires a HTML change to fix, it would be bumped to Header.5.1.1, so that anyone looking to use the latest version of Header can quickly see some work is required to adopt it.

.
One UI-Kit changelog page
:+1: :+1: I think that is a good idea! So that progress as a whole is easier to track.
(CC: @patrick @alex.page)

4 Likes
#5

But that didn’t actually happen? Or is it a future plan to do so?

I can see the benefit of not having the global version thought.
Thanks for the explanation.

#6

That was as my understanding of how it worked but I’ve just been looking at the readme files for the components and it’s not super clear to me either… maybe one of the devs can shine some light on it? @alex.page @dominik

1 Like
#7

We updated core to a new major version because we changed a function inside of core. The function was the a11yColor function which received a performance improvement. We removed a property in the function. This function only gets ran in the core component and the output of the function has not changed. Due to this we only updated a major version of core and patched the other components to use that new major version.

If we changed a function that applied spacing that affected all of the components we would be publishing new major versions for everything. We are trying our best to follow semver as closely as possible.

3 Likes