Proposal: versioning policy

[sobolevn]

Currently master branch contains several features that only django@3 has.
Which makes 2.2 releases no longer possible. And it is a long time support (LTS) release.
Which means that we probably should support it for a long time.

That's why I propose to use something similar to https://github.com/python/typeshed
We need to structure types under specific versions if we want to make this project maintainable in the long run.

Something like this:

django-stubs/
- 2.2
- - db # (full types)
- 3.0
- - db  # (diff from 2.2)

@mkurnikov what do you think?

[mkurnikov]

Isn't typeshed directory structure special cased in mypy?

Also, could you elaborate?

Which makes 2.2 releases no longer possible.

[sobolevn]

Merging PRs like this one #256 messes up types for other supported versions. For example, people using 2.2 will see types that are only added to 3.0. And as it seems to me this problem will be quite frequent.

[sobolevn]

Related #439

[blueyed]

Isn't typeshed directory structure special cased in mypy?

Has this been investigated into?
I.e. is it possible to support the suggested directory structure in the first place?

Apart from that I've thought that different (release) branches could be used maybe, but that does not scale probably.

[sobolevn]

Apart from that I've thought that different (release) branches could be used maybe, but that does not scale probably.

Yes, I thought about it, but because I am mostly a single person with merging rights who maintain this project (with a lot of help from our awesome contributors and community!), it will surely consume a huge amount of my time 😢

Other solutions do not seem viable at all. I would be happy to be proven wrong here.

For now, we are just using complex "compatibility matrix" that does not suit everyone, but is something.
https://github.com/typeddjango/django-stubs#version-compatibility

[mkurnikov]

@sobolevn

I am mostly a single person with merging rights who maintain this project

Thank you very much for taking over the project, I would've been a bummer to have it die because I moved to other stuff.

What do you think about the versioning scheme I proposed in #288? Like, source code will be filled with those conditionals, but for the actual PyPI release, there will be a script that will create packages for different Django versions. And version name will be like 1.8.0.2.2 (the first part is django-stubs version, and the second part is the supported Django version).

[sobolevn]

Libcst has some serious problems: first of all, it does not work with python3.9+ (because of peg-parser)
Secondly, putting lots of conditionals might be really hard to read. But, I think that that it is a good thing to try at least.

[mkurnikov]

it does not work with python3.9+

It only needs to be able to parse stubs, and I think .pyi files use python3.6 grammar (variable annotations), right? So, it shouldn't matter.

As for the "hard to read" argument, it depends on the context. It certainly breaks pip install -e which creates a bit of friction in development. But if you'd want to read it from your Python IDE to see what's the stubs are, it'll already be in the post-processed state, so no conditionals there.

[sobolevn]

As for the "hard to read" argument, it depends on the context. It certainly breaks pip install -e

When this transformation will happen? Do we have to package it properly? Or can our users continue to use it when installing from git?

[mkurnikov]

In setup.py using pyproject.toml build dependencies? (I never actually used it, don't know whether it would work).

[sobolevn]

It might work! 🤔

[sobolevn]

What about file renames and location changes?

[intgr]

Per proposal in #1095 (comment), the consensus seems to be to move to supporting just one Django version for the time being.

I am closing this issue but have interlinked this in relevant issues for historical reference.