Please remove dependency pinning, at least for MkDocs

[oprypin]

The recent sentiment in Python world is that upper range dependency restrictions are harmful in libraries.

As for MkDocs itself, I routinely test that I don't break plugins with new releases, via https://github.com/mkdocs/regressions, so it's even more unnecessary.

Please remove these upper range restrictions:

mkdocs-rss-plugin/setup.py

Lines 54 to 55 in 910de75

	"GitPython>=3.1,<3.2",
	"mkdocs>=1.1,<1.4",

All this does is cause unnecessary issues:

• Build failing on site with blog - 8.5.5-insiders-4.24.2  squidfunk/mkdocs-material#4438 (comment)
• mkdocs-git-committers-plugin-2 has an invalid wheel [was: Changes in MkDocs v1.4.0 causing deploy error] ojacques/mkdocs-git-committers-plugin-2#21 (comment)

---

• Meanwhile, a new release is needed in any case, with Update mkdocs requirement from <1.4,>=1.1 to >=1.1,<1.5 #135

[Guts]

Thanks you for your interest and taking time to argue here.

Sorry, I don't have time (maintaining it on my spare time) to make a complete answer to explain why I prefer to stay conservative on the "ceiling" version but I have published a version compatible with mkdocs<1.5: https://github.com/Guts/mkdocs-rss-plugin/releases/tag/1.2.0

I hope it will unlock dependent projects.

I'm already working on a 1.3.0 with #133 and using changes introduced in mkdocs 1.4.0 for plugin development.

[josh-wong]

Thanks for the quick fix, @Guts!🙏🏻

I've confirmed that mkdocs-rss-plugin - v1.2.0 works as expected and MkDocs sites build without errors again.

... I have published a version compatible with mkdocs<1.5

When MkDocs is inevitably updated to v1.5.0, will mkdocs-rss-plugin break again? Or will the error we encountered this time be resolved when you release mkdocs-rss-plugin v1.3.0?

[oprypin]

It will break again

[josh-wong]

It will break again

@oprypin On the surface, I know that. I'm using a slightly different communication technique than you use to politely ask him if he can expand on his plans for v1.3.0, in the hope that he can reduce maintenance on his behalf.

[Guts]

Sorry for the delay but I have prioritized work on improvements (see releases 1.3 and 1.4).

@oprypin from my own experience, I have often faced problems with the dependencies my developments are based on... or I myself have been tempted to bend SemVer when releasing my own package.
So I have become cautious or even conservative about the dependency framework, both minimum and maximum.

On the other hand, the development of this plugin (quite already mature), remains reasonably active and I do not feel that I have delayed too much to publish a compatible version with the 1.4 of Mkdocs.

I don't think this has been such a burden to other projects, except maybe early-adopters? This plugin is not so wide-used, is it?

I'm still convinced that taking the time to test that everything is going well and that there were no unexpected breaks is rather a guarantee of quality and making the plugin reliable. Users can wait 2 weeks no?

On the other hand, the development of this plugin, already mature, remains reasonably active and I do not feel that I have delayed too much to make it compatible with the 1.4 of Mkdocs.

I don't think that this has been too much of a hindrance to projects, except maybe early-adopters?

I'm still convinced that taking the time to test that everything is going well and that there were no unexpected breaks is rather a guarantee of quality, isn't it?

On the other hand, the development of this plugin, already mature, remains reasonably active and I do not feel that I have delayed too much to make it compatible with the 1.4 of Mkdocs.

I don't think that this has been too much of a hindrance to projects, except maybe early-adopters?

That being said, if it's really blocking, I'm willing to try to upgrade to <2 but will put it back if it goes wrong or if I get overwhelmed with requests (again: here is a spare time project).

What do you think @oprypin @josh-wong and others that have reacted?

[oprypin]

I can understand you're frustrated about packages that make breaking changes, indeed they shouldn't do it. Still though, part of my point is that Python packaging is simply not good enough to be able to handle upper version restrictions in a user-friendly way and so its failure modes are worse than actual breakages just because they're more typical and more confusing.

I don't think this has been such a burden to other projects, except maybe early-adopters? This plugin is not so wide-used, is it?

This plugin will probably be widely used now because it is recommended on the most popular MkDocs-related site: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#rss , in addition to being shipped in its Docker image. Not that this should be used as an argument.

Users can wait 2 weeks no?

Users could wait if the tooling made it possible for them to understand that that's the case. But, in several typical (but unfortunate) setups all they can conclude is "MkDocs recently made a new release and now everything broke".
Just look at the linked issues.

1. They installed MkDocs 1.4.0, then installed this plugin, during which pip silently overwrote it with MkDocs 1.3.1. Then the mkdocs-material theme crashes, because it no longer expects MkDocs 1.3.1! And the user just straight up says they have MkDocs 1.4.0 because it's what they specified initially but which is untrue. Now the issue spans across 4 different participants: the user, mkdocs maintainer, mkdocs-material maintainer, and eventually mkdocs-rss-plugin maintainer. All of which need to scramble and check "so what did I just break?" - but not just that - I literally had to decipher from the stack trace that the code matches up with MkDocs 1.3.1, otherwise we wouldn't have known.

2. The issue thankfully pops up at the packaging level, but still the user states in the title that MkDocs 1.4.0 broke them.

These made me feel anxious because I have just made a risky release of MkDocs, so of course I immerse myself in these. Only to find out that actually I didn't break anything - and it's not even about any particular piece of code - and even so, I'm powerless to stop the issue reports from coming in.

Moreover, I spent a very large amount of effort to not make breaking changes to MkDocs 1.4 and in particular as I mentioned, I tested that various sites, including plugins, get rendered exactly the same in the new version.
All of that just to see claims from users that MkDocs 1.4 broke them. I mean, that's a wrongful reputation hit, however small.

I was further frustrated by the fact that 0 of the mentioned issues were caused by the particular 1.4 version, the same can happen with any version bump. And none of this needs to happen! Just if the version pinning is gone.

 

You have mentioned several times that it's a spare-time project for you. Well, MkDocs is a spare-time project for me! I don't receive anything from it. Same probably goes about most plugin developers.

 

BTW I also did a rough search and it appears that mkdocs-rss-plugin is the only plugin that has MkDocs pinned to something <1.*.

Please indeed do remove the version cap.

The main article to read on this is:
Should You Use Upper Bound Version Constraints? • TL;DR.

If you want to be particularly sure about breakage checks against your plugin, feel free to provide example MkDocs sites exercising your plugin (perhaps write it as a new issue) and I will be sure to add them to my collection of checks that I run before releasing.

[Guts]

Thanks again @oprypin for taking time to argue here. It's really nice and very interesting.

Well, MkDocs is a spare-time project for me!

Really? Woa, quite impressive... and scaring somehow. It sounds like a big mental load! Congrats for your work 👏. If I mention it, this is because I'm regularly surprised how people use their free time to criticize projects made on the free time of another one...

The main article to read on this is:
Should You Use Upper Bound Version Constraints? • TL;DR.

2 hours later... No, I'm just kidding, I've read it completely and saved it to share later with my teams. Thanks for the reference.

I get the main line but I want to take time to digest all the arguments and think about it before make my own opinion.

In the meanwhile, because this plugin is a little package which should not interfere with the main project it's based on, I've raised up the upper cap to the major version in #146. If everything goes well, I would remove it completely.

[oprypin]

Thanks! 🙂

[Guts]

Release 1.4.1 brings this decision to live: https://github.com/Guts/mkdocs-rss-plugin/releases/tag/1.4.1

I close here.