Name the main command django

[jeff]

How did you feel about a less disruptive change of #1 and #3 as Ryan outlined?

django-admin should stick around (almost indefinitely IMO) but be phased out over a much, much longer period of time to avoid any and all disruption.

[KenWhitesell]

I’m fine with the rest of it. Even the thought of django-admin going away doesn’t strike me with the same degree of dread as the thought of manage being made obsolete because of all the automation we’ve built around running custom management commands. Anything changing the semantics of manage.py has the potential of being extremely disruptive to us.

[ryanhiebert]

@KenWhitesell

because of all the automation we’ve built around running custom management commands

This has been eye-opening for me, and I really appreciate the perspective you’ve brought to the discussion. The manage.py script has always felt so ad-hoc to me that I never considered building tooling around it. It makes sense now that it’s brought up, and I’ve had cases in my own experience that reinforce it, but I wouldn’t have guessed it from the bias of my own perspective that it had become such a major interface for automation.

[thibaudcolas]

@ryanhiebert

• Add a django command as an alias of django-admin.
• Add configuration to pyproject.toml for the settings module.
• Switch docs to use django instead of django-admin.
• Switch docs to use configured django instead of python manage.py.
• Switch the default template to no longer include python manage.py.

+1, +1, +1, +1, +1. Looking forward to less needless typing!

[michjnich]

I am +1 on django as an alternative to django-admin, and even replacing it as the default command in the docs. It’s nicer, cleaner, easier for newcomers to understand.

That said, I think django-admin needs to stay just because Django has been around so long. If you were going to deprecate that it would be a long way in the future so as not to break a load of workflows!

Default settings module in pyproject.toml I’m less keen on tbh.

If I’m deploying a “regular” django project, there is potentially no need for pyproject.toml to be there at all I don’t think, especially if I’m doing everything I can to slim down multi-stage container build. It’s got all my linting/type check/test config in, the requirements etc. but at the moment there’s nothing in there that the project itself depends on once it’s actually installed, so adding something there feels like a big step. I’ve sort of seen pyproject.toml as great for package setup/install and tool configuration, but unnecessary for something like a django project - or am I way off base here?

Oh, and one extra consideration … I, like many others, tend to have a src directory with my actual project code in. Root contains docker stuff, dotfiles, makefiles and stuff like that. At the moment I usually have a manage.py alias at root to src/manage.py, but if we’re replacing with django it needs to have a way to tell it what the root for the actual django path is (i.e. src in my case) so I don’t run it in project root and suddenly create a new app there or something

[ryanhiebert]

@michjnich

At the moment I usually have a manage.py alias at root to src/manage.py

TIL that Python knows about symlinks when it’s determining the directory to automatically add to the path.

@michjnich

it needs to have a way to tell it what the root for the actual django path is

yes!

[CodenameTim]

@ryanhiebert

• Add a django command as an alias of django-admin.
• Add configuration to pyproject.toml for the settings module.
• Switch docs to use django instead of django-admin.
• Switch docs to use configured django instead of python manage.py.
• Switch the default template to no longer include python manage.py.

+1, 0, +1, 0, -1 (now it needs more text)

[nessita]

Hello everyone,

I have read this thread, and the referenced developers thread from 2015. So far I think the situation is a as follows:

• There is an inclination to go with 1 (django alias) and 3 (change it in docs).
• I think it’s clear that 5 (remove manage.py) is a no-no, which makes 4 (remove manage.py from docs) a more clear no as well.
• Then, there is 2 (add? use? pyproject.toml) which I’m not 100% sure what the proposal entails. If it means to change the startproject template to drop a pyproject.toml in the project folder, I’m strongly against it. We can’t impose using pyproject.toml on a project, and is not something that users will necessarily know about or even wanna use. Lots of project use alternative tooling for this or even not tooling at all.

Given the above, below I’ll only comment on 1 and 3. I think most of the commentary from 2015 still holds and I would like to highlight the one from @apollo13 (answering to “[is] django-admin is a good command name?”:

Does not really matter imo, that is what we have now and we should not change this without a really good reason.

From my reading so far, the reasons to make this change are:

1. django-admin could confuse readers/users about its relationship with the “Django Admin”. Django teachers out there (@wsvincent and others), have you seen this in the field?
2. django it’s shorter and “sweeter”.

On the other hand, let’s list the reasons to not make this change:

1. From Aymeric Augustin:

[django-admin] it’s a reasonably unambiguous way to refer to the django-admin command, which is good for the docs.
“django” is more ambiguous: it can refer to the framework itself (although incorrectly capitalized) or to the top-level Python package.

2. The docs explain what does the admin mean in it, which I think still holds:

django-admin is Django’s command-line utility for administrative tasks. This document outlines all it can do.

3. Changing docs invalidates all existing translations for the paragraphs that has it.
4. It adds yet another way to do something, going against the Python Zen. There is an agreement that we can’t remove the existing ones, so we would be only adding. Isn’t this confusion worse than wondering once why is it called django-admin?

Personal Experience:

1. I’ve never had to type out the full django-admin name. Just typing dj<TAB><TAB> autocompletes it. So, is character length really an issue?
2. When setting up a project, I only use django-admin once, to run startproject. After that, I never use it again. Everything else is managed via manage.py. Is it worth invalidating hundreds of existing docs and tutorials for a change that might only be used once per project?

Conclusion:

I honestly don’t see the benefit when weighed against the disruption it could cause. As a Fellow, I wouldn’t block the change if everyone is on board with the alias, but what exactly are we gaining here?

For point 3, as a Fellow, I’d need to request that alongside the documentation changes, there’s a commitment to update all translations to ensure that every instance of django-admin in the docs is properly updated in existing translations. This is a considerable amount of work. Is there someone who will take ownership of this effort?

(Point 3 would also affect all the books, tutorials, and other resources that still use django-admin. While they wouldn’t necessarily need to update it, they would suddenly appear outdated or incorrect, which could pressure them to make changes.)

[CodenameTim]

I’m looking at this as a very slow move to retire django-admin and manage.py. Similar to Model.Meta.unique_together. With this option, documentation and content can start adopting the new version. Overtime, the older ways become more of, “Oh yeah, that’s still around. We should clean that up.” With that perspective things may look a bit different.

@nessita

It adds yet another way to do something, going against the Python Zen. There is an agreement that we can’t remove the existing ones, so we would be only adding. Isn’t this confusion worse than wondering once why is it called django-admin?

That’s fair. It does. But you can do a lot of the same things with django-admin as you can with manage.py. Is there not an argument to be made that is duplication of functionality that’s confusing to users? If we can merge them down the line, we end up with one way to do things.

Would you agree that’s a benefit worth pursuing?

@nessita

For point 3, as a Fellow, I’d need to request that alongside the documentation changes, there’s a commitment to update all translations to ensure that every instance of django-admin in the docs is properly updated in existing translations. This is a considerable amount of work. Is there someone who will take ownership of this effort?

I would agree with having someone taking ownership of this project to the finish.

[tom]

Since I also wrote about this recently, I should chime in. Somehow I didn’t see this post yet.

I’m definitely +1 on 1 and 3. I would go a bit further and actually make django-admin an alias of django, just to drill it in a bit.

2 might be nice if I can get enough interest in a new startproject command to add a pyproject.toml (I think it’s a good idea). 4 and 5 follow from this and are also a bit of a maybe. Certainly I don’t want to break anyone’s project, but I imagine existing ones would still work perfectly well, and I probably wouldn’t want to force existing projects to do this. Some people add extra code into manage.py for good reason. But I’d suggest 2 / 4 / 5 can all be proposed separately and have those conversations in a different place.

I’m not going to try to rationalise it by giving reasons why I think it’s technically better. Fewer characters or less confusing with the Django Admin. I’m not very concerned about those reasons, and I share Natalia’s opinion that they don’t really matter. The reason I like this is because it’s intuitive. It has better aesthetics, which I believe is more important than people give it credit for. Running django-admin feels crusty. Feels like I’m in an 80s CLI. Do you run vite-admin, or rails-admin? No. And nobody (seemingly) gets confused that rails doesn’t mean the framework as a whole.

I just think that it looks nicer, which is an important thing when newcomers are reading the tutorial for the first time. It’s also much easier to remember, which is also important for newcomers.

I think Django could stand to be a bit more fun, intuitive, generally easier to grok and this feels to me like a reasonably straightforward way to do it.

[ryanhiebert]

@nessita

For point 3, as a Fellow, I’d need to request that alongside the documentation changes, there’s a commitment to update all translations to ensure that every instance of django-admin in the docs is properly updated in existing translations. This is a considerable amount of work. Is there someone who will take ownership of this effort?

I’m willing to take ownership of whatever part of the implementation we decide to do.

[tom]

@tom

Fewer characters

Although I will say… I’ve coached at a handful of Django Girls workshops. Every time I teach someone about pressing tab to complete commands and files, I almost invariably get the same result: “oh! that’s pretty cool” - and they never remember to use it again. It takes some time when you’re new to programming to get this habit into your muscle memory.

[ryanhiebert]

Just so folks are aware, if we choose to separate out 1 & 2, I’ll probably drag my feet a bit on implementation of the django command, to see if I can find a way to avoid breaking reading the pyproject.toml in django-cmd, since there would end up with a name collision in the command. Obviously that’s not Django’s concern to think about, it’s mine, but I would be thinking about it as I go to implement it.

[emma]

@ryanhiebert

• Add a django command as an alias of django-admin.
• Add configuration to pyproject.toml for the settings module.
• Switch docs to use django instead of django-admin.
• Switch docs to use configured django instead of python manage.py.
• Switch the default template to no longer include python manage.py.

1. +1 - I remember this being very confusing when I first started using Django and to quote @tom I don’t see this being confusing for users of other frameworks such as rails or ember
2. +/-1 - while I don’t think it’s agood idea to impose a pyproject.toml because of the diversity of the tooling landscape, I also don’t see why it couldn’t be an option, ie: django startproject --toml
3. +1 (or vice-versa, django-admin becoming an alias to django). While it is important to keep the docs up-to-date, having both for a while allows for documentation and tutorials to be upgraded gradually (ie:not a big deal if we miss one somewhere)
4. +1/0 - I believe uniformity is key and it will be less confusing for new users. As long as we keep manage.py alongside, I don’t see how this would break things but moving forward there will be a unified way of doing things.
5. -1/0 - This would probably break every single deploy script out there. I am not sure what other automations people are referring to here so I also don’t see how deprecating manage.py would be different to other deprecations (ie: you see a deprecation warning while testing or deploying, at some point you are going to have to address it). I would therefore more positive to it if we could agree on a longer deprecation period.

[ubernostrum]

Assuming that the request is to have startproject create a pyproject.toml, I have to admit I’m a bit surprised at the resistance to that suggestion. Given the variety of popular tools which configure via that file – and some very popular ones like black which can only be configured via that file – I’m curious why it would be seen as a bad thing for Django to generate one.

[tom]

I do agree with this. I was going to say it’s the future, but to be honest, it’s the present. It’s been quite some time already since I’ve needed a setup.py, setup.cfg, or requirements.in, not to mention all the single tool config files I used to need floating around.

I would also be incredibly surprised if this file goes away any time soon after all the battles fought to get it where it is now.

I’m aware there are some pyproject.toml haters, but nothing is stopping them from deleting it.

The only argument I can think of against this is that we currently don’t generate any other sort of opinionated configuration, so it’s new territory in that respect.

[KenWhitesell]

@emma

I am not sure what other automations people are referring to here so I also don’t see how deprecating manage.py would be different to other deprecations

Speaking strictly for myself and the type of work I do, roughly 25% of my deployments are tools that don’t create web pages or support the HTTP protocol. They’re either network listeners writing data to databases, or Channels workers doing work from channel messages. What they all have in common is that they are either written as custom management commands or started using the runworker management command - which all rely upon manage.py.

These manage.py references to run those instances exist in countless systemd service files, cron jobs, supervisord config files, docker-related files, etc, which are deployed via ansible scripts or package files.

Now, in reality, removing the existing manage.py just adds one step to our development process of new projects - creating a manage.py. We could probably even keep the existing startproject template and use that moving forward. So from that perspective, it doesn’t have that significant of an effect on us.

But at this point in time, getting rid of manage.py, regardless of the deprecation process, is a non-starter for me. At a minimum, what that creates is a disparity in how those systems are being run, and I don’t see any upside with that. We’d need to track and know whether project “X” for Django 8.2 was created for Django 8.2 without a manage.py file, or was a Django 2.2 project that has been continuously updated.

[tom]

@KenWhitesell

Now, in reality, removing the existing manage.py just adds one step to our development process of new projects - creating a manage.py. We could probably even keep the existing startproject template and use that moving forward. So from that perspective, it doesn’t have that significant of an effect on us.

But at this point in time, getting rid of manage.py, regardless of the deprecation process, is a non-starter for me. At a minimum, what that creates is a disparity in how those systems are being run, and I don’t see any upside with that. We’d need to track and know whether project “X” for Django 8.2 was created for Django 8.2 without a manage.py file, or was a Django 2.2 project that has been continuously updated.

Ken, I find myself a bit confused by your message. I think this is my fault for not comprehending it. I don’t have a strong opinion either way. But are you saying here that removing manage.py would be fine for you as long as it was supported / easy to create your own? Or that you’d rather keep it for new projects entirely?

This makes me think a bit about my DEP for the new command. Currently the reference implementation keeps manage.py for both the new default template and the classic template, but I could see a future where I change the default template to include pyproejct.toml instead of manage.py, but leave the classic template with manage.py - would this be reasonable for you? This way both continue to be perfectly well supported.

[carltongibson]

There seem to be three issues here.

The rename. One way to do it vs probably more fun. We should be able to decide this easily enough, but should probably hold off until after the holidays are over and most people are in a position to see the discussion.

The pyproject.toml suggestion, which may be a good idea (or not) but seems orthogonal to the original idea Jeff proposed. (Like maybe IDK: there are folks that like to make their app packagable, but most users likely never think about that.)

Removing manage.py, which would be massively disruptive, for what gain I can’t see. Every tutorial, every doc, every project in the history of Django… I’d be very much -1 on removing this. Maybe there’s a case to made here, but removing something so central to the existing user experience needs much more thought if it’s to be seriously considered.

Three ideas: All the time in Django we take a small idea and chain it to other changes which leads into controversy. We should try to keep them separate to allow progress. As I say, focusing on the first issue would seem like something we could settle (one way or the other)

Enjoy the rest of the holidays!

[KenWhitesell]

@tom

Ken, I find myself a bit confused by your message.

Yea, I rambled a bit as I was thinking things through as I wrote it. I can see where I was trying to address multiple subtopics at the same time.

To take a step back just a little, the original question included the phrase:

@emma

I also don’t see how deprecating manage.py would be different to other deprecations

So, to try and isolate my perspective of that part of the question -

Removing manage.py affects how other systems might interact with your Django project.

This is different from all other deprecations that I can think of that has affected me. Every other deprecation that I can remember was internal to the Django project itself. Yes they required changes to the project, but had no effect on how those projects were deployed to the various environments in which they were being used.

(I have to heavily qualify my statements here because I need to freely acknowledge the possibility of other features being deprecated that would have had a similar effect - however, I can’t think of any, which implies that I either never used those features in a project where it would be subject to these concerns, or they were used and deprecated prior to our current deployment processes.)

@tom

But are you saying here that removing manage.py would be fine for you as long as it was supported / easy to create your own?

Yes, this probably expresses it the best. If the Django project startproject no longer created a manage.py, we would need to do something to create one ourselves. In the grand scheme of things, I’m sure it’s what we would call a minor lift.

So does it need to be part of a new startproject command? (Or new command?) No.

Would we like to see it remain as an option (e.g. --make-manage)? Sure, that would work.

Would we like to see it as perhaps a new or different command? (e.g. django make-manage) That would work too. But if it were removed completely from the ecosystem, we’d end up writing our own. (And if that were to need to occur, any tooling provided within Django to support that would be appreciated.)

And so that’s the other part of my answer, and I hope I’m more clear here.

I’m a -1 on removing manage.py for the reasons I’ve tried to explain above.

I’m 0 on changing startproject such that creating manage.py becomes either an additional parameter or even a separate command. (I don’t see a benefit to this, but there’s no tangible downside, either.)