Given a version number MAJOR.MINOR.PATCH, increment the:
1. MAJOR version when you make incompatible API changes
That's one opinion.
Another opinion is, that API and major version changes can be used whenever the maintainers of an open source project feel like it. No other reason is necessary. Because it's their project. They write the code. They don't have to justify that decision.
If a large portion of the projects userbase is unhappy about that, the project will lose traction and new project, or a fork, will arise.
Speaking of that, flask 2 was released in May 21. I can't really complain about some breaking changes every 2 years or so. That's almost like a linux distribution.
So they should tie the development to an extension that isn't in further development?
No they are not.
The flask team announces changes, deprecates things and uses major versions correctly. The major version change also doesn't happen frequently.
If a package absolutely requires a certain version, IT CAN SPECIFY AS MUCH in its requirements. If it doesn't, tough luck.
```
def some_function(*args, **kwargs) -> JSON:
...
```
2 years (flask 2.0 release) should be plenty for deprecation notice.
The numbering scheme is meant to give predictability to breaking changes or backwards compatibility, so if followed correctly, it absolutely should make it suck less.
Yes it does, because that "numbering scheme" tells my users when and if breaking changes happen.
It also allows them to avoid them. Don't want to keep up with the dependency? Make the version a hard requirement. Done.
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.
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'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!
This is really just another instance of CADT, imho.
I can't help with books- and IMHO, this is why books are obsolete for internet technology. I used to be a big OReilly fan, but at some point, the books were worse than useless because none of the examples would work 10 years later. Now, examples don't work 1 year later!
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.
This is a bit like a No True Scotsman argument. It says that there are reasons for what happened but they didn't have a Good Reason. Why are their reasons so particularly trivial?
> try to learn Flask in a world like the one you describe
This seems moot if the Flask maintainers are using semantic versioning correctly. I'd probably look into it and think that Flask-Login maintainers should have limited their Flask version if they were going to step away from maintenance. If someone else wants to pick it up they can fork it or try to get in touch with the old maintainers to get access to the central repo.
The learning material should specify a major version so this doesn’t happen.
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.
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.
But one thing that needs to be acknowledged is how difficult it is to coordinate a space with so many stakeholders (eg. Conda and Anaconda for Windows), and how python got so engrained in the sys admin (installing tools with pip.) that undoing that is a monstrous task [1]
[1] The other day my ansible playbooks stopped working because packages that you used to be able to install globally with pip, should now be installed through the package managers (eg. jsondiff should now be installed as apt-get install pyton3-jsondiff). Exactly to push people to use virtual environments where you can better manage depedencies.
You can lock Python versions.
But people by default, people type pip/npm/apt/yum install without the version.
Nothing unique to Python.
For example, despite all the problems of JS, new devs don't need to create a virtual environment and activate it all the time. They don't need to manually add lines to a requirements.txt, or pick a tool like poetry or pip env [1]
[1] Edit: ok they have to pick yarn/npm, but even those share a common file base formate - package.json
> pip install foo==1.2.3
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.
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.
But big things (OS, framework etc) have code squirreled away all over the world.
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.
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.
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.
> 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.
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.
But trying to follow along to a tutorial that is old and asks you to install latest version of anything likely means that you won't get far.
As someone that's written many tutorials, I've been guilty of using "latest" but have been much more proactive here to call out specific versions used at the top of my articles. Nothing worse than getting through half a tutorial to find out something has completely changed.
They shouldn't.
They should be doing specified versions, either precise or bounded to the degree you trust the dependency suppliers semver compliance.
> 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.
No. It doesn't. You document what version is covered. You then have the choice to update that or not.
OTOH, failing to specify dependency versions means every time abmny of the dependencies releases a new version, the tutorial potentially breaks, which is much worse than working fine but not using a newer version of a dependency when you are not, in either case, using any new features of the new version. (Because if you aren’t upgrading the tutorial, its not covering features of the new version, even if the loosely-specified packages mean uses will pull in the new versions.)
You shouldn't need to. How/why are you writing tutorials for major versions that don't exist yet?
> `pip install flask` installs the latest version, which is 2.0 at the time of writing
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
Key packages are developed by the community so lack of understanding or no cooperation with Parallels it's not really a Flask issue.
Unfortunately the only solutions for this are:
* Join Parallels and try to change things.
* Use different package, there's plenty web frameworks.
* Understand better semver, and python should try to promote this, or move away from semver to calendar releases like Ubuntu/Jetbrains
I'm still interested in any countervailing opinions on this particular detail.
https://github.com/wangsha/flask-login/commit/6d1b352dd5106e...
but not yet released.
This is more an issue with versioning
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.