Clay: Can we make the global changelog more useful?

[wincent]

So we have a global changelog now (since #3898) and the bot that comments with an LPS link when PRs make it into releases that are bound for liferay-portal (since #3917).

One small obvious change we could make to improve the usefulness of the global change log would be to aggregate the updates which are just "noise" (the "version bump only for package" ones) so that the ones which are "signal" (marked in pink in this screenshot) would stand out:

Something like this:

# YYYY-MM-DD release

## @clayui/package-with-real-changes (x.y.z)

### Features

- ...

### Bug Fixes

- ...

## Version bumps only

- @clayui/package-without-significant-changes-a (x.y.z)
- @clayui/package-without-significant-changes-b (x.y.z)

A bigger change than just formatting the changelog in a more useful way would be to switch from independent releases to releasing everything at once. We've discussed this before (at least in #3214 and other places too, no doubt), but it's worth remembering that it is a possibility. IIRC, the main argument against is "why bump the version number for all the packages that didn't actually change in a release? isn't that misleading? wasteful?" but on the flip side it represents a massive simplification from the perspective of the user...

Instead of having about 39 different Clay packages with (literally) 23 different version numbers like we currently do in liferay-portal:

"@clayui/alert": "3.5.1",
"@clayui/autocomplete": "3.2.6",
"@clayui/badge": "3.2.0",
"@clayui/breadcrumb": "3.3.6",
"@clayui/button": "3.6.0",
"@clayui/card": "3.6.6",
"@clayui/charts": "3.2.0",
"@clayui/color-picker": "3.5.0",
"@clayui/css": "3.24.1",
"@clayui/data-provider": "3.3.10",
"@clayui/date-picker": "3.8.0",
"@clayui/drop-down": "3.9.1",
"@clayui/empty-state": "3.2.0",
"@clayui/form": "3.14.4",
"@clayui/icon": "3.1.0",
"@clayui/label": "3.4.1",
"@clayui/layout": "3.3.0",
"@clayui/link": "3.2.0",
"@clayui/list": "3.4.7",
"@clayui/loading-indicator": "3.2.0",
"@clayui/management-toolbar": "3.3.0",
"@clayui/modal": "3.8.5",
"@clayui/multi-select": "3.9.4",
"@clayui/multi-step-nav": "3.3.6",
"@clayui/nav": "3.4.5",
"@clayui/navigation-bar": "3.3.5",
"@clayui/pagination": "3.3.6",
"@clayui/pagination-bar": "3.2.6",
"@clayui/panel": "3.3.6",
"@clayui/popover": "3.5.5",
"@clayui/progress-bar": "3.2.0",
"@clayui/shared": "3.5.1",
"@clayui/slider": "3.2.0",
"@clayui/sticker": "3.3.0",
"@clayui/table": "3.1.0",
"@clayui/tabs": "3.3.5",
"@clayui/time-picker": "3.2.6",
"@clayui/toolbar": "3.0.6",
"@clayui/tooltip": "3.4.5",
"@clayui/upper-toolbar": "3.1.14",

we could have 39 packages with a single version number that could be easily understood by developers as "version x.y.z of all these Clay packages" that are all known to work correctly and cohesively together. This is what we did for Clay v2, as you probably recall.

Another argument against going away from independent versioning was that we'd lose the ability to make breaking changes (ie. say we wanted to bump _one_ package to v4 to make a breaking change, we'd have to bump _all_ of them). But the pressure to avoid breaking changes at all costs is probably a feature and not a bug. 🤔

Anyway, if we did that, the global changelog would lose the "version bump" updates entirely and could just be:

# x.y.z

## @clayui/package-with-actual-changes

### Features

- ...

(ie. packages without actual changes would just be omitted from the changelog entirely).

Anyway, I think both of these options are worth considering if you want to keep Clay as a separate repo, because it helps alleviate some of the pain points and makes it easier to fend off the case for moving it into DXP (ie. #3849).

[matuzalemsteles]

Yeah in general I think it would be a good idea to remove the changelog noises, this will definitely decrease the size and also improve the reading as much as the search.

Regarding making all the components have the same version, we even used it that way in the first versions of 3.x and one thing we were doing that was being cool, was to create the release notes that helped give an impression of what we did it, well I think it was working well, some people had liked the idea but I also like the benefit of doing the individual release but I realize that now when we do a release many packages just update their patch version due to the dependencies between the packages, which ends up with a change affecting some other packages. I would say that I sit on the fence here and I am fine with any decision 😁

[bryceosterhaus]

I agree on reducing the noise of the changelog, I think it would be nice benefit to group all the "version bumps" together.

As for the the release mode, I think it's worth looking into doing away with independent releases. I forget the exact reasons why we wanted to go with independent, but I think it had to do with the idea of being able to do one off releases of individual packages. Looking over the last year, I don't think using independent mode has really helped us all.

Anyways, long story short, I'm gonna look into this more and at bare minimum update the changelog and then additionally check out single releases.

[matuzalemsteles]

I think one of the main reasons for using the individual release was when we started to release the stable version of Clay 3.x and we needed to release it quickly due to the deadline we had to meet. In order for a component not to crash the release, in the end we went with the individual release that allowed us to release stable components without having to wait for everyone, this worked very well for us at that time when we didn't have much time.

[bryceosterhaus]

Moving from independent mode to fixed mode in lerna seems pretty reasonable to me. I just looked into it for a bit and I don't see any major downsides for us and we actually sort of already operate in a fixed manner anyways. All of our components are essentially tied to the version of @clayui/css and can't really operate independently of that package. So I am up for flipping it to fixed.

In order to move to fixed, we just need to update the version in our lerna.json to be 3.24.1(the version of @clayui/css). And then additionally we need to make a note in our changelog for the packages that jump from like 3.2.0 to 3.24.1 that the drastic increment was due to changing our release mode. Luckily, none of this should matter a ton for users since they primarily consume clay via dxp.

Any opposed?

[jbalsas]

Any opposed?

[github-actions[bot]]

This issue has been merged and will be released in DXP at https://issues.liferay.com/browse/LPS-126700