What we can do with breaking changes?

[ZeaLoVe]

With rapid iteration, some functional features may conflict with previous versions. These conflicts can affect users' usage. Is there a way to highlight this in the release note or weekly report? Also, can such a feature design be brought up for discussion earlier?

Especially SQL dialect changed, commands changed.

[flaneur2020]

I guess we can mark the changed behaviour with a semantic release manner: make a BREAKING: as prefix in the pull request.

and we need some introduction about why this behaviour is changed to users.

[ZeaLoVe]

Release note maybe not be enough, it just shows in the single release version, but breaking affects the following versions. Better a page to show all breaking infomation.
Like https://etcd.io/docs/v3.5/upgrades/upgrading-etcd/. If there is breaking, pick the version in upgrading pages, show all breaking changes on this page, and better some guides.

[Xuanwo]

Here are some experiences from OpenDAL

OpenDAL doesn't reach 1.0, so OpenDAL can introduce breaking changes between minor versions. To make our users happier, OpenDAL maintains a Upgrade docs. OpenDAL will record the changes and how to migrate from existing code for every breaking change. Sometimes, we will add links to RFC to explain why we introduce this change.

For example, OpenDAL 0.12 adds breaking changes, so we have the following section:

FYI: https://opendal.databend.rs/upgrade.html