Release notes are difficult to associate with package versions

[IronSean]

Description

Currently release notes are sent out with every release in the form of a blog post. These blog posts are dated, but do not show the version numbers of the packages. The installed npm packages however use semver. To answer the question "have any released changes addressed a problem I'm experiencing, and are there any breaking changes I need to be aware of to update?" neither the github releases or the release notes posts provide all the answers.

By looking for the tag for the version I have installed I can determine what date it was released, then start finding the relevant blog posts. But it would be easier if this information was all in one place. Even including the tinacms package version in the release notes as a lowest common denominator might be helpful. A CHANGELOG.md which just contains a link to the blog posts might also be helpful to others.

[ncphillips]

This is a problem that I has been annoying me basically since this project started. Unfortunately I don't really know what we should do.

Here's the crux of the issue. As of today, the tinacms/tinacms monorepo contains about 35 packages. In order to make developing and publishing this vast array of packages easier, we use lerna. Lerna makes it so you can link all local versions of the packages together during development. It also lets you publish them all at once using conventional-commits.

Lerna let's you choose between independent and fixed vesioning schemes. In independent versioning, every package has it's own version number. In fixed versioning, every package has the same version number.

This project uses independent versioning. The reason it does that is that a lot of the packages are totally decoupled. If we were to use fixed versioning then it would break semver on all of the packages. For example, updates to next-tinacms-github will never effect anybody that uses gastby-tinacms-git, but with fixed versioning a new feature added to the next package would create a minor version bump in the gatsby package. As the project grows, we might start having dozens of packages having new versions published even if they don't need them.

My suspicion is that it might be better if all the core packages (i.e. those scoped to @tinacms were versioned together) and other packages were not then it would be fine. As far as I know lerna does not allow for this. This means the only way we could do this is by moving the non-core packages out of the monorepo into other repositories. This would solve the problem for people using Tina, but it would make developing Tina harder because it would increase the difficulty of developing non-core packages using the local core packages.

Either way we should at least at the current tinacms package version to the Release Notes

In summary

• Keep with independent versioning and just add tinacms@0.x.y to the release notes
• Switch to fixed versioning and forget about semver
• Move all non-core packages from the mono repo and put them in other packages.
• Ditch lerna for something else only to find out that sucks too
• Ditch lerna to build our owns solution only to find out that sucks even worse

As it stands, I'm kind of leaning towards option 2. I'm pretty much fed up with the current approach and I'm not sure I care about semver. There's a lot of advantages to going with the fixed approach (i.e. versioning documentation, identifying mismatched versions in your package.json) but it might be problematic.

Worst case scenario we have to switch back. Should that happen it won't be that big of a deal. We're pre-1.0 so I'm willing to be a bit annoying. Right now I care more about the project being designed and managed well then I do in maintaining API so to speak.

That said, I would love to hear your opinion @IronSean, as well as the opinion of anyone else who might be interested.

[chrisdmacrae]

@ncphillips you could pull off a double monorepo in a single git repo with Lerna by doing:

|-- core
|--- lerna.json.    => 1
|- packages
|--- lerna.json     => 2
|- lerna.json        => 3

Where:

1. Handles publishing core fixed
   1. It would need to read ../packages/ potentially, but ignore them for publishing
2. Handles publishing packages independant
   1. It would need to read '../core` potentially, but ignore them for publishing
3. Handles development concerns
   1. It would need a config to prevent publishing?

[IronSean]

Yeah, I knew this would be a real dog of an issue when I mentioned it. There are so many decoupled packages involved there's no simple answer.

I figured just associating the tinacms root package version like you mentioned in option 1 might be nice since everyone will have it, everyone will possibly be updating packages at the same time, and it'll probably update versions more often then not. But faces the limitation that some weeks it might not actually get any releases and suddenly the whole "one helpful hint" approach breaks down. It's definitely the simplest incomplete bandage.

For option 2, I've used collections of packages before that use that approach: every package gets a version bump even if nothing has changed. As a developer it's easy to reference one set of release notes with one version number, and it's easy to know that all your versions are in sync. It's also fairly easy to just bump them all up at the same time. It definitely causes some release bloat though, where multiple package versions are the same code. It ends up being semver for the entire project ecosystem instead of individual packages.

But npm should mostly handle that package version bloat. And although there are 35 packages currently, it seems most developers only install a handful in a given project. As a developer I don't find it unreasonable to go "oh library collection X has had a release, time to update them all to 2.2.3".

I also don't know if semver for individual packages provides value in the context of tinacms. If gatsby-tinacms-git has a breaking change I don't want to update to, and I update tinacms to a version that expects it to be updated I'll get a peer dependency error anyway. And if I'm updating any tinacms packages, I imagine under most circumstances I would update them all. If I decided not to update one for some reason I would probably hold off on updating any. Although decoupled, I wouldn't feel comfortable mixing and matching old and new plugin versions without having intimate knowledge of all their relationships.

That said, if @chrisdmacrae's approach above works, that might be a nice compromise of getting all the core packages on a fixed version scheme, and leaving the secondary packages that are unlikely to frequently update to do their thing. If Gatsby somehow goes completely out of fashion, you could stop updating those related packages and leave them at their final release. I think that approach could also work for a fixed versioning scheme, where gatsby-tinacms-git gets left at 2.5.1 while tinacms continued to >3, but I don't know how annoying configuring lerna to stop updating a package is if you switch to fixed globally.

Edit: Maybe a similar example could be the react ecosystem. react and react-dom, etc keep the same versioning when they're designed to be used together.

[ncphillips]

This is some really great feedback.

t'll probably update versions more often then not. But faces the limitation that some weeks it might not actually get any releases

This is definitely happens. Not super often, but sometimes we're totally focused on improving specific non-core behaviour.

As a developer it's easy to reference one set of release notes with one version number, and it's easy to know that all your versions are in sync. It's also fairly easy to just bump them all up at the same time.

This is the major benefit in my eyes. Seems like the downside is low, and the benefits to both maintainers and developers is high.

wouldn't feel comfortable mixing and matching old and new plugin versions without having intimate knowledge of all their relationships.

This is a really good point. Doing that is something someone might do in theory, but so far I doubt it would happen in practice.

but I don't know how annoying configuring lerna to stop updating a package is if you switch to fixed globally.

If it really became that stale we could remove the package from the repository

[jeffsee55]

Sorry if I'm missing this context but it's not clear why these version bumps are happening? Does Lerna think there's a change when there isn't? As far as I know Lerna is able to look at the previous changes for a package

[ncphillips]

Sorry if I'm missing this context but it's not clear why these version bumps are happening? Does Lerna think there's a change when there isn't? As far as I know Lerna is able to look at the previous changes for a package – @jeffsee55

With fixed every package gets bumped always as they all have the same version number.

With independent, if a package's dependency gets bumped then it gets a patch bump to update the dependency version number. For example, if I change @tinacms/core then basically every package in the repository gets a patch bump. But if I change react-tinacms-github then no other package gets updated.

[ncphillips]

The real issue though isn't the version numbers, it's how does someone using make sense of the version numbers? How can they use the version numbers and changelogs to figure out what changes they might have to make?

[IronSean]

Fun fact: Shift+enter in github posts your comment instead of a line break. And I think it even chose "Close and Comment" over "Comment"

A sort of out there idea would be a mixed mode: Packages always update to the same version, but the version only increment when there are changes.

i.e.
pA 1.0.0, pB, 1.0.0, pAB 1.0.0 //initial state
pA 1.0.1, pB, 1.0.0, pAB 1.0.1 // update pA, pAB also updates because pA is a dep.
pA 1.0.1, pB, 1.0.0, pAB 1.0.2 // update pAB, nothing else was changed
pA 1.0.1, pB, 1.1.0, pAB 1.1.0 // update pB, pAB updates because it's a dependency.

I can't decide if this is a good or awful idea. I'm probably just high on fumes since my mental gas tank is about empty for the day. It definitely isn't supported out of the box with Lerna. And it's not a pattern I've seen before so it's sort of confusing. But Tina release 1.1.0 would only update the necessary packages and npm would tell you if everything was at it's latest.

[sakulstra]

Hello, i thought it might make sense to drop my 2ct here as well - essentially another option to #1331 (comment) :
just do a monorepo and a topic specific changelog.

---

I just upgraded to apollo-client@3 and have to say working with it is a breeze.

1. you have single package shipping all the bells and whistles instead of x package
2. local development and linking the package is super easy as it's a single package (didn't do that yet, but with tina i did and it's a tad annoying as you have to link multiple packages)

What exactly is the big advantage of shipping all these tinacms parts (from which in a lot of cases a big subset is used together at some point) as multiple packages? A medium post on that topic.

[ncphillips]

Hey @sakulstra thanks for the input! I intend on writing more about this in the future but I'll answer in short here. The main thing is that Tina is a not meant to be a standalone application, but a toolkit for building CMSs. We provide many tools for people using Tina in different use-cases. One reason why this matters is bundle sizes. People using next-tinacms-github shouldn't need to use gatsby-tinacms-git, and vice versa. We even extracted react-tinacms-editor so you can leave the wysiwyg out entirely, or at least load it more efficiently. This idea extends even to some of the "core" tinacms features. Making it possible to remove the tinacms package from your website would be quite difficult, but because of the more decouple structure developers with serious performance constraints can by-pass it and get more control over their website and CMS. There's certainly downsides to using the decoupled mult-package architecture, but in the case of Tina it is the most appropriate structure for our goals.

[sakulstra]

While I was/still am following that thinking for some projects I think the point on bundle size is not true when using modern bundlers and side effect free code.

When using parts of gql-client, lodash or material-ui, you only pay the price for e.g. popper.js in bundle size when you import sth using popper.

Anyhow that's just food for thought. I realized that 100% of my private monorepo usage is in fact unnnecessary which got me thinking it might be the case with Tina as well.
Tina is as it is, is incredible cool - I'm happy to continue importing a few modules 😅

[ncphillips]

Having switched to fixed versioning I think this issue is resolved.

Here's the first Release Notes post after switching

Here's the project wide CHANGELOG