dotnet
Please could compatibility be taken more seriously?
I've just spent many hours today upgrading NodaTime from 2.62.2 to 2.75.2. I'm mostly there now, but I've just run into a problem with version support disappearing between the two.
I've eventually found where this happened - in a commit with a title of "refactor: rename config property to match json", which apparently failed in CI and wasn't in a pull request (was it even reviewed)?
It removes properties from FileMappingItem, including VersionName (with JSON representation version) and then removes the use of that. How does that count as a refactoring? This change was then released in a patch release.
I've lost hope of there not being any breaking changes in docfx within a major version, but I'd really appreciate it if:
- Breaking changes are only introduced in minor versions at least rather than patch
- Every breaking change comes with details of how users are meant to migrate, or an acknowledgement that features are simply being removed with no migration path
- More attention is paid to conventional commits so that "refactoring" commits really don't introduce breaking changes
Thanks for your feedback, Jon - I totally agree with you and apologize for the trouble that commit caused you. Proper versioning and change management are critical in all projects, but particularly in libraries that other people depend on. We didn't do a good job here, but we'll work to be better in the future.
Our goal is to clean up the code, fix some known problems, and remove code that was never fully implemented or was specific to internal-only features when DocFX was used to generate Microsoft's docs.microsoft.com site. Microsoft no longer uses this code directly and has a different implementation that is aligned more to the dynamic nature of what the Microsoft Learn site has evolved into. As such, the supporting community can evolve DocFX with some cool new ideas - but we need to be more careful to ensure we don't introduce breaking changes, or if we do, to ensure we version and document it properly. Thank you for reminding us of that!
We'll be more careful in the future and provide more opportunity for people to review the plans as preview versions before pulling them into a formal version.
