Possibly unreported breaking change

[anmolshres98]

Hi, I noticed that changes from this commit aren't available in the changelogs. This commit has some breaking changes - namely TreeWidgetUiItemsProvider not being exported from @itwin/tree-widget-react anymore. (There might be more but investigating this change on my app lead to that issue in particular). I was looking for a migration guide or notes on this breaking change but couldn't find any when moving from 2.x to 3.x. Let me know if this is an oversight on my part and this is documented and I just failed to located the docs 😄

[anmolshres98]

Update: I did locate the mention to this here: https://github.com/iTwin/viewer-components-react/blob/master/packages/itwin/tree-widget/README.md#30-highlights but I still do think it should show in Changelogs too under 3.0 major changes? or am I missing something?

[grigasp]

Hi @anmolshres98, thanks for you message. The 3.0 release has breaking changes to pretty much every component in the package. Instead of naming each of them in a changelog and trying to come up with some migration guides, we invested our time in a good README. Since the APIs changed that much, I believe there's not much more value in migration guide over a startup guide. And the latter also helps to new consumers.

Is there some missing information in the README that you would find useful? I would be more than happy to make improvements there.

[anmolshres98]

Hi @grigasp , thanks for the response and yes that makes sense.

I do think though that most devs who are just looking to bump their package version to 3.0 will first go to changelogs to see what all the breaking changes are and not necessarily the README. The norm in industry seems to be that READMEs are static so I and many other devs might not think to check the README first when looking for major changes. This does work greatly for new devs looking to consume this package but breaks expectations of more experienced devs specifically since the changelogs do list some major changes - which gives the impression that all major changes are as listed there and one needn't go to the README for more information.

I have found the README to be quite helpful when it comes to migrating and integrating new features. Perhaps, a link or mention to the README in the changelog would help out other devs that go down the same path as me 😊. I don't feel very strongly about it or anything though so feel free to use your discretion and close this issue if you disagree and are ok with docs as is.

[grigasp]

I agree our changelogs aren't great, and part of the problem there is that we're limited by the tool we're using to generate them - beachball. It allows providing only a single paragraph per change without any markdown in it, so there's not much flexibility - we can't add examples, links, lists, etc.

As a solution, I propose switching to using changesets - it provides the same versioning capabilities, but much better experience with changelogs. For example, compare tree-widget-react CHANGELOG, generated with beachball, vs presentation-hierarchies CHANGELOG, generated with changesets.

Switching the tool would slightly change the way we generate changelogs, so I need agreement from other maintainers in this repo.
Tagging code owners of packages in this repo to hear their opinion: @aruniverse @a-gagnon @itwin/insights-and-reporting-platform @mdastous-bentley. Please let us know what you think.

[grigasp]

P.S. I'll try to come up with a way to point consumers to README from the 3.0 major changes section in CHANGELOG.

[aruniverse]

Switching the tool would slightly change the way we generate changelogs, so I need agreement from other maintainers in this repo.
Tagging code owners of packages in this repo to hear their opinion: @aruniverse @a-gagnon @iTwin/insights-and-reporting-platform @mdastous-bentley. Please let us know what you think.

I'd be ok with the change as long as its not too disruptive and there isnt too much overhead compared to using beachball
Maybe lets track this in a separate issue

[grigasp]

Switching the tool would slightly change the way we generate changelogs, so I need agreement from other maintainers in this repo.
Tagging code owners of packages in this repo to hear their opinion: @aruniverse @a-gagnon @iTwin/insights-and-reporting-platform @mdastous-bentley. Please let us know what you think.

I'd be ok with the change as long as its not too disruptive and there isnt too much overhead compared to using beachball Maybe lets track this in a separate issue

#1125