The post's point is that an API change is a very big deal, to be used only when the older version just can't work anymore or the newer version offers something much better. But the Flask team seems to have a much lower bar on what justifies the change. So the author feels unhappy he has to update a bunch of projects for no good reason.
In essence, I'm pretty sure plenty of the changes in the set of parameters that are actually acceptable quite often changes accidentally (same for what's in the JSON)
I have long advocated the idea that online tutorials should have unit tests: there should be a daily build that loads the tutorial, extracts the code bits, runs them, and reports a failure if a dependency broke the tutorial.
And those tutorials should have the ability to force rollbacks of minor point releases that break backwards compatibility.
Tutorials should be pinned to major point releases.
I have designed a personal tutorial authoring system that does exactly this, forcing you to include expected outputs in your article, which act as unit tests.
However the idea kinda went nowhere as the main issue with writing tutorials is that you gotta compete with websites with poorly written, ad-riddled articles that are somehow ranked on top by Google; and furthermore the end is near for such tutorial websites anyway given the proliferation of ChatGPT/GPT4.
I used to work on Sage, a math super package, which used 'doc tests' - documentation strings contained executable examples with expected outputs, and the test systems would run them all and check that they worked.
Explain to me how you would apply this concept to a book. Or to a YouTube video.
I'm not unreasonable, I get that things have to change from time to time. I just think maintainers should think more carefully when they introduce breaking changes. The cost to them is very high!
That reminds me my history with Ruby. Got to the famous "blog in 15 minutes" tutorial, used the stuff that comes with OS, nothing worked, didn't touch ruby again till I had to.
So consider what happens when you try to learn Flask in a world like the one you describe. You pip install Flask, and you get 3.0. Next chapter asks you to install Flask-Login, and now you are forced to downgrade Flask.
What you are saying makes sense when there are important reasons to break compatiblity. But I expect the Flask side to love their users a bit more and not break their code for trivial reasons.
The problem stems from how fragmented dependency management in python is. Most tutorials use `pip install something` without much care for pinning versions.
Yes, it makes it easier for new programmers: They can skip learning a dependency management tool like poetry, or pipenv. But then these things happen.
Blame the tutorial makers and the dependency maintainers, not the Flask team.
> Blame the tutorial makers and the dependency maintainers
I'd blame the python community as a whole, for not driving everybody (flask team, tutorial makers, dependency maintainers, etc) towards pinned versions.
This is a well-established problem in any environment where you write code that has dependencies. Strict use of semver, and tools that respect those conventions, would solve MOST of this.
Python dependency management certainly has many problems, but I don't think this is one of them--or at least, it's not a problem unique to Python. The practice of tutorials/docs/guides installing unpinned/latest versions is incredibly common in most (all?) scripting languages' communities. While that's not great, I don't think it has anything to do with the fragmentation of Python's dependency management.
Despite the "it's your fault" vibe towards Miguel, I have to say: thank you Miguel!!
Your tutorial was a turning point for me 4 years ago, the care you take to write and help people is very precious. My ability to write modest web apps takes its roots in your free online materials, I am grateful for that.
Any older product will fall into disrepair, simply due to the decreased attention old features get. Plus the years of accumulated of references to any particular feature, that would take years to track and put right whenever it changes.
Not sure there's any cure.
I hit this (OP) issue myself. Solved it somehow, don't remember, just another glitch in the neverending series of glitches that are open-source lack-of-support and obsolete documentation.
Just today, noticed Steam tutorial videos generally use some obsolete version of their website tools. Have to fish around, find where the menus etc are, they sure aren't where the video says they are.
The cure is to put a test on it (beyonce rule), and make the test passing required for release. And do rapid rollbacks (within 1 day) if bad releases are made.
It seems unreasonable to expect anything that relies on "version:latest" to not break upon a major version change.
What makes a tutorial different than any other software process, in this context?
Your tutorial was written and functions for a particular version of a software. Pin that version. It's the straightforward thing to do.
Frankly, I would be insulted if I was miseducated by a tutorial that purports to be up to date, but was actually written for a old major version. Learning obsolete techniques, missing best-practices.
Right. The closest analogy I can think of is answers on Stack Overflow. Usually those answers apply to the latest version of whatever software they're about, but this means many of them will eventually be out of date. You can find plenty of answers with code that assumes Python 2, written by authors who had no idea there was going to be a Python 3.
And that's okay. It's not a bad thing for answers to sometimes go out of date.
A really good answer might specify the major version of software it references, just to be future proof, but that isn't strictly necessary since anyone can just add a new answer and old answers can be edited (on Stack Overflow). For tutorials, it's much more incumbent on them not to mislead users into following an old tutorial, since most people will want to start with the latest version. Put a banner at the top that says "this is a tutorial for Flask 2.x, the latest version of Flask at the time of writing", and/or pin versions in your installation instructions.
I've been maintaining my Build a SAAS App with Flask video course[0] for 8 years. It has gone from Flask pre-1.0 to 2.3 and has been recorded twice with tons of incremental updates added over the years to keep things current.
In my opinion tutorial creators should pin their versions so that anyone taking the course or going through the tutorial will have a working set up that matches the video or written material.
I'm all for keeping things up to date and do update things every few months but expecting anyone can install any version doesn't tend to work well for tutorials because sometimes bumping a minor version requires a code change or covering new concepts. As a tutorial consumer it's frustrating when the content doesn't match the source code unless it's something simple like a version bump.
As a tutorial creator it's your responsibility to ensure things work which ultimately leads to doing everything in your power to remove time as a variable. You can commit a frozen dependency file which locks everything. I sleep pretty well at night knowing things will work tomorrow. Before I did that I had all sorts of things break over the years due to some dependency of a dependency introducing a backwards incompatible change. Now it's predictable and I can control when it's safe to update a set of packages.
I've held off upgrading Flask to 3.0 and Python 3.12 due to these open issues with popular 3rd party packages https://github.com/nickjj/docker-flask-example/issues/17. I'm sure new releases will get pushed in due time. When they are good to go then I'll add a new video update and all is well for everyone. Maintainers can work at their own pace, I can verify everything works in production and then roll it into the course and folks taking the course get an up to date version that's been proven to work.
This is a wider issue with Flask and the surrounding ecosystem, and is also why I switched to Django a couple of years ago. I don't recall which package it was specifically, but there was a commonly used security package that was recommended by lots of blogs and tutorials, but the maintainer no longer wanted to maintain it but also didn't want to let anyone else contribute. So it led to another developer forking it and adding a '2' to the end of the name just to keep it current. This wouldn't have been such a big issue if the package didn't add really important security features to Flask, but due to the minimal nature of Flask it really depends on having a well-managed ecosystem of packages. My takeaway was that I felt I couldn't rely on Flask for an application that required features that weren't in the main Flask package itself.
But just wanted to also say, that the main reason I enjoyed working with Flask at the time, was due to Miguel's excellent mega-tutorial. Again, that speaks to the value of having a good ecosystem to support your solution. Flask have ultimately shot themselves in the foot by releasing something they must have known would break a huge number of sites, without bringing the community along with them on the journey.
Normally tutorials ask readers to install latest versions of everything. If you have to provide a version for every package used in a tutorial, it means that every time any of such dependencies releases a new version the tutorial has to be updated. I guess it is possible for a blog post, but how can I update my books or my videos?
By reading many of the comments here, it looks like that you are missing the point (maybe you are not a Flask user): it would be great if Flask would only introduce breaking changes in major releases. Unfortunately, many things break with minor releases too.
We develop a framework built with Flask, and it is very painful. We always pin Flask< minor version (not major).
This is unfortunately happening with other software too. The community should really align and stick to SemVer.
It’s not missing the point, it’s that the author of this screed lead with whining about a project breaking compatibility on a major release. Since most of the software world has collectively agreed that’s how it’s supposed to work, whatever else they wrote is going to be buried because the author chose to start the post that way. Since they picked a deliberately provocative title there’s little chance that’s going to be a salvageable conversation.
It seems to me that the problem here is that everyone directly depends on pypi. The Debian model would be to introduce another repository layer, explicitly to say "everything you install from this repository will work together". Hoping to achieve the same effect with version numbers is a fool's errand, especially when nobody agrees what version numbers mean.
So this is yet another post about how terrible is the python ecosystem with the versions.
The author of the post seems unfamiliar with the meaning of a major release.
maxcountryman (author of flask-login) doesn't know how to pin down versions.
I'm not a big fan of Flask to be honest but this doesn't seem a problem from them. I'd rather blame maxcountryman , the author of the post or pip for this case
Flask is a minimal web framework that relies on its ecosystem of packages and tutorials to keep it current and relevant. So yes, this is a problem for Flask if key packages that are recommended in just about all tutorials do not keep up to date.
My assertion is that none of the refactorings in the 3.0 release bring a benefit to the community. I did not imply that the entire 3.0 release is void of improvements.
Hence why I prefer Django over Flask any day. Less moving parts, more stability. I even upgraded Django apps from one major version to another with little to no change to the apps.
This occurs all the time when using LLMs for code due to the variety of versions of each lib in their training data (which is typically years old already)
Some sort of automatic functionality to find deltas in libraries (even just crude function inspection between versions) and detect/remap them (or roll back versions) might solve that and issues like this.
usrbinbash|2 years ago
vharuck|2 years ago
fiddlerwoaroof|2 years ago
regularfry|2 years ago
toolslive|2 years ago
ilyt|2 years ago
2 years (flask 2.0 release) should be plenty for deprecation notice.
skrebbel|2 years ago
dekhn|2 years ago
And those tutorials should have the ability to force rollbacks of minor point releases that break backwards compatibility.
Tutorials should be pinned to major point releases.
supriyo-biswas|2 years ago
However the idea kinda went nowhere as the main issue with writing tutorials is that you gotta compete with websites with poorly written, ad-riddled articles that are somehow ranked on top by Google; and furthermore the end is near for such tutorial websites anyway given the proliferation of ChatGPT/GPT4.
sdenton4|2 years ago
miguelgrinberg|2 years ago
I'm not unreasonable, I get that things have to change from time to time. I just think maintainers should think more carefully when they introduce breaking changes. The cost to them is very high!
ilyt|2 years ago
mmnfrdmcx|2 years ago
miguelgrinberg|2 years ago
What you are saying makes sense when there are important reasons to break compatiblity. But I expect the Flask side to love their users a bit more and not break their code for trivial reasons.
sergioisidoro|2 years ago
Yes, it makes it easier for new programmers: They can skip learning a dependency management tool like poetry, or pipenv. But then these things happen.
Blame the tutorial makers and the dependency maintainers, not the Flask team.
kennywinker|2 years ago
I'd blame the python community as a whole, for not driving everybody (flask team, tutorial makers, dependency maintainers, etc) towards pinned versions.
This is a well-established problem in any environment where you write code that has dependencies. Strict use of semver, and tools that respect those conventions, would solve MOST of this.
zbentley|2 years ago
gaganyaan|2 years ago
> pip install foo==1.2.3
kyawzazaw|2 years ago
pil0u|2 years ago
Your tutorial was a turning point for me 4 years ago, the care you take to write and help people is very precious. My ability to write modest web apps takes its roots in your free online materials, I am grateful for that.
JoeAltmaier|2 years ago
Not sure there's any cure.
I hit this (OP) issue myself. Solved it somehow, don't remember, just another glitch in the neverending series of glitches that are open-source lack-of-support and obsolete documentation.
Just today, noticed Steam tutorial videos generally use some obsolete version of their website tools. Have to fish around, find where the menus etc are, they sure aren't where the video says they are.
Business as usual.
dekhn|2 years ago
pphysch|2 years ago
What makes a tutorial different than any other software process, in this context?
Your tutorial was written and functions for a particular version of a software. Pin that version. It's the straightforward thing to do.
Frankly, I would be insulted if I was miseducated by a tutorial that purports to be up to date, but was actually written for a old major version. Learning obsolete techniques, missing best-practices.
bscphil|2 years ago
And that's okay. It's not a bad thing for answers to sometimes go out of date.
A really good answer might specify the major version of software it references, just to be future proof, but that isn't strictly necessary since anyone can just add a new answer and old answers can be edited (on Stack Overflow). For tutorials, it's much more incumbent on them not to mislead users into following an old tutorial, since most people will want to start with the latest version. Put a banner at the top that says "this is a tutorial for Flask 2.x, the latest version of Flask at the time of writing", and/or pin versions in your installation instructions.
nickjj|2 years ago
In my opinion tutorial creators should pin their versions so that anyone taking the course or going through the tutorial will have a working set up that matches the video or written material.
I'm all for keeping things up to date and do update things every few months but expecting anyone can install any version doesn't tend to work well for tutorials because sometimes bumping a minor version requires a code change or covering new concepts. As a tutorial consumer it's frustrating when the content doesn't match the source code unless it's something simple like a version bump.
As a tutorial creator it's your responsibility to ensure things work which ultimately leads to doing everything in your power to remove time as a variable. You can commit a frozen dependency file which locks everything. I sleep pretty well at night knowing things will work tomorrow. Before I did that I had all sorts of things break over the years due to some dependency of a dependency introducing a backwards incompatible change. Now it's predictable and I can control when it's safe to update a set of packages.
I've held off upgrading Flask to 3.0 and Python 3.12 due to these open issues with popular 3rd party packages https://github.com/nickjj/docker-flask-example/issues/17. I'm sure new releases will get pushed in due time. When they are good to go then I'll add a new video update and all is well for everyone. Maintainers can work at their own pace, I can verify everything works in production and then roll it into the course and folks taking the course get an up to date version that's been proven to work.
[0]: https://buildasaasappwithflask.com/
paulddraper|2 years ago
> Flask 3.0 was released on September 30th, 2023, along with a parallel 3.0 release of Werkzeug
> That day, the Flask-Login extension, one of the most popular of all Flask extensions, stopped working
Every major release BY DEFINITION will break things.
And breaking "that day"? It's really "that second" or "that nanosecond" by the same standard.
---
You can complain about one of two things:
1. Flask did not need to developed a backwards incompatible 3.0 release, but could have developed a backwards compatible 2.* release.
2. Flask-login is too slow to release a version compatible with the newest version of Flask released 3 weeks ago.
But this blog post presents it in...such a weird way.
amanzi|2 years ago
But just wanted to also say, that the main reason I enjoyed working with Flask at the time, was due to Miguel's excellent mega-tutorial. Again, that speaks to the value of having a good ecosystem to support your solution. Flask have ultimately shot themselves in the foot by releasing something they must have known would break a huge number of sites, without bringing the community along with them on the journey.
hiatus|2 years ago
miguelgrinberg|2 years ago
nicoz3|2 years ago
acdha|2 years ago
regularfry|2 years ago
Saphyel|2 years ago
The author of the post seems unfamiliar with the meaning of a major release.
maxcountryman (author of flask-login) doesn't know how to pin down versions.
I'm not a big fan of Flask to be honest but this doesn't seem a problem from them. I'd rather blame maxcountryman , the author of the post or pip for this case
amanzi|2 years ago
jollyllama|2 years ago
miguelgrinberg|2 years ago
rs_rs_rs_rs_rs|2 years ago
JodieBenitez|2 years ago
bigdog42|2 years ago
https://github.com/wangsha/flask-login/commit/6d1b352dd5106e...
but not yet released.
This is more an issue with versioning
Forgotthepass8|2 years ago
Some sort of automatic functionality to find deltas in libraries (even just crude function inspection between versions) and detect/remap them (or roll back versions) might solve that and issues like this.
unknown|2 years ago
[deleted]