Documenter.jl: semver issues (could you consider releasing version 1.0 or continuing with 0.27.xxx)
I was very excited to use the new 0.27 version, mainly because of the outdated warnings feature (thank you for making all of that!). However, my documentation requires packages that extend Documenter and because of how Documenter does version numbering I had to wait for them to update their compat versions, even though Documenter was not introducing breaking changes.
To avoid similar issues, could you consider continuing forward with version 1.0 or doing 0.27.1 instead of 0.28? I think I am not suggesting anything controversial as that is the julia prescription for semver <1.0. I think this PSA pinned by Stefan Karpinski confirms that: https://discourse.julialang.org/t/psa-if-your-packages-version-is-of-the-form-0-y-z-please-do-not-bump-the-minor-version-for-new-features/46570
Krastanov
>All comments
I briefly addressed this here: https://discourse.julialang.org/t/ann-documenter-0-27/62726/17
As for packages that are extending Documenter: if they depend on Documenter, they are likely diving into the internals, none of which is technically part of the public API. So there is a very good chance that some refactoring of the internals will break the dependent packages. So I would argue that, for now, it is actually good if the developers of the extensions are being force to verify that their package still works any time we make some non-trivial amount of changes.
All that said, I do not disagree that we would ideally do better with this. It is just that Documenter is somewhat complex, and so getting semver right for it requires time and effort. In the meanwhile, my opinion is that putting a tiny bit of extra work on the users' shoulders is an acceptable trade-off if it means we avoid breaking their setups.
mortenpi
on 18 Jun 2021
Related issues
nalimilan
路
4Comments
BioTurboNick
路
5Comments
halirutan
路
4Comments
Roger-luo
路
3Comments
juliohm
路
6Comments
Most helpful comment
I briefly addressed this here: https://discourse.julialang.org/t/ann-documenter-0-27/62726/17
As for packages that are extending Documenter: if they depend on Documenter, they are likely diving into the internals, none of which is technically part of the public API. So there is a very good chance that some refactoring of the internals will break the dependent packages. So I would argue that, for now, it is actually good if the developers of the extensions are being force to verify that their package still works any time we make some non-trivial amount of changes.
All that said, I do not disagree that we would ideally do better with this. It is just that Documenter is somewhat complex, and so getting semver right for it requires time and effort. In the meanwhile, my opinion is that putting a tiny bit of extra work on the users' shoulders is an acceptable trade-off if it means we avoid breaking their setups.