Add django command

[ryanhiebert]

Motivated by a desire to remove confusing papercuts in Django and to follow common convention in the Python ecosystem, this DEP proposes to add a new django command equivalent to the existing django-admin command, and to update the documentation to prefer this new spelling.

Forum discussion
Rendered

[shaib]

We can mitigate some of the "multiple spelling" issue, by having django-admin not as a completely equivalent alias to django, but as a thin wrapper that invokes django and prints a message along the lines of

The django-admin command is being renamed to django. You can keep using either name, they are equivalent except for the printing of this message. For more details on the naming change, see (link to DEP 100).

[ryanhiebert]

a thin wrapper that invokes django and prints a message

Thanks for that suggestion. I've worked it in. I think it'll make it a little easier to start any discussion about it.

[RealOrangeOne]

Love this idea ❤️

[merwok]

Did you mean uvx django ?

[ryanhiebert]

Yes!

[ulgens]

Is this completely anecdotal, or do we have any data points from a survey?

[jefftriplett]

We could add it to future surveys if more people think it'd be a useful data point.

My data point is asking while on the stage at DjangoCon US and seeing over half the room hold up their hands every time I ask them if they learned Python by learning Django.

[ulgens]

Thank you. I feel like this mention is worth having a reference for, but I guess it's too late now.

[tim-schilling]

There are a total of 13 questions asked, for 3600+ views starting back in 2016. Typically, I would say this is small, but if we look at it from the perspective of first-time django devs, it seems to be common enough for us to improve.

• https://stackoverflow.com/search?q=%22No+module+named+django-admin%22
• https://forum.djangoproject.com/search?q=%22No%20module%20named%20django-admin%22
• https://groups.google.com/g/django-users/search?q=%22No%20module%20named%20django-admin%22
• Django Discord shows 6 questions with "No module named django-admin"
• Python Discord shows 1 question with "No module named django-admin"

[tim-schilling]

Personally, I'd like to see this not be the case. Having the message when people use django-admin, but never planning on removing it feels like unnecessary noise. [Or have the warning message removed until we have a plan in place. Otherwise we're going to end up with another setting to disable that messaging.]

[ryanhiebert]

There are competing community values that I'm trying to navigate:

1. Introduce the preferable spelling, django
2. Avoid breaking existing material that uses django-admin
3. Have only one way to do it
4. Avoid noisy warnings that don't have a clear time horizon

I don't see a way to have all four of these at the same time. If we skip the warning, we have more than one way to do it. If we set a clear duration on the warning then we will break existing material at that point in the future.

The persistent warning without a time horizon felt like a reasonable way to soft-enforce "one way to do it" without breaking existing material; adding a setting could further soften the enforcement. The warning is visible to developers using Django, without breaking any commands. That can give us some time to have a better sense of whether the community will ever want to remove the old way, or whether we'd rather compromise on "only one way to do it".

If the project is prepared to make that choice now rather than wait, I'm happy for that. I think that my preference would be the same as yours: let's plan to remove it at some specific point in the future. It might deserve a longer deprecation period due to the centrality of the command, although I think I'd personally be inclined stick with the policy as stated.

I suspect this DEP won't be able to be resolved without the SC determining the right way to balance these competing values, because key members of the community disagree on which values should have the highest priority for this question. Would it be best for the purpose of lining this question up for the SC to modify this DEP with a more aggressive deprecation suggestion, or keep it as-is?

[LilyFirefly]

I'm happy with either the current proposal or with setting an explicit timeline, though I think it should be longer than our usual deprecation cycles to allow the tutorial ecosystem to migrate.

[jefftriplett]

+1 to phasing django-admin out over a really long time. I agree with Tim that we should have an appropriate warning message, but my gut feel is that we should phase it in a bit slower than we might otherwise.

[adamchainz]

I'm +1 for keeping django-admin indefinitely. pytest still has its legacy py.test command with no plans to deprecate, and it doesn't seem to harm users. What does hurt is when production scripts with no version control break due to the command going missing. In such cases, deprecation warnings are often never seen because they're piped into ignored logs.

But I'd also be okay with something quite long-term, like "After two major versions, it will be deprecated" would be okay. We can use language similar to Python 3.14's announcement of the new compression module:

Any deprecation or removal of the existing compression modules will occur no sooner than five years after the release of 3.14.

[nanuxbe]

As others have mentioned, my only concern with this is the lack of planned deprecation for the django-admin command.
I agree that this will need non-standard, longer term deprecation than the usual, so it might be best to come up with that in a separate PR/discussion/place

[LilyFirefly]

This DEP is now accepted. All members of the Steering Council are in favour (I've spoken with @carltongibson in person).

@ryanhiebert @knyghty Can one of you make the requested changes to this PR? Then it can be merged.

[tim-schilling]

I technically approved in Slack. All good here.

[knyghty]

Amazing, thank you everyone!

[Antoliny0919]

Amazing, I’m looking forward to this change 🙌🙌