Name the main command django

Django Internals
42

I want to point out a couple quick things here:

  • It’s not the case that “pyproject.toml exists” implies “is a package/is meant to build a package/is packageable”. Informally, that stopped being the case about five minutes after the basic format of the file was standardized, because people started shoving completely-non-packaging-related config into it. Formally, it stopped being the case more recently when even the Python packaging community finally threw in the towel and started working out what it officially means to have a pyproject.toml in a source tree from which packages will never be built. So if the resistance is due to an assumption that pyproject.toml necessarily implies intent to build a package, that assumption is wrong.
  • Depending on what sorts of command-line entry points are desired, pyproject.toml may well be the correct place to define them. At the very least, how to define entry points generically in pyproject.toml is now well-specified, and does not depend on any third-party build backend or other tool to provide the support.

I still think given the sheer volume of popular Python tools which are standardizing on “config goes in pyproject.toml” it’s a bit weird that Django doesn’t add one to newly-created projects.

3 Likes
43

To raise a point I don’t think has been mentioned yet … think about how many people/crontabs/systems/admins/devops stuff/etc. may have python manage.py ... in there somewhere - scheduled tasks, manual support processes, scripts to copy/manipulate data etc. A lot of tools are built as management commands and then run with python manage.py <cmd>, and it’s not just changing scripts, it’s likely in a lot of internal process documentation too at many sites.

Deprecating this very slowly is perhaps possible, but I’m pretty sure that even if it is not a breaking change for many django “projects”, it may well be a breaking change for many systems that revolve around django.

44

Just to clarify for anyone that might not have caught the difference. Nobody is considering deprecating any existing manage.py scripts. Those will continue to work indefinitely. The only things we’re considering changing are (a) the docs to use a django command with a project-configured settings module, and (b) maybe dropping the manage.py from the default project template from django-admin startproject.

2 Likes
45

I’ve opened a minimal PR to add the django spelling. Other than mentioning it briefly in the release notes, it doesn’t update the docs to switch everything to the new spelling, because I want to take my time with that work to make sure I do it as correctly and thoroughly as I can, but I’d like to not miss the feature freeze if possible.

I was able to figure out an alternative solution for django-cmd, so I’m no longer worried about it causing unreconcilable conflicts between the two packages.

46

This is also my experience. I imagine many in favor of the rename must be specifying their settings file differently and using django-admin instead of manage.py, thus the “pain” of typing “django-admin”? But, as suggested, won’t typing dj<tab> already give the same result?

It’s interesting to me that the rename proposal got no traction when it was proposed previously (several -1’s on GitHub, no support on the mailing list), but in this thread it has many +1’s with little pushback except Natalia. Count me as a skeptic too, though I think it makes more sense in the context of the full proposal where this is no need for manage.py and “django” becomes the primary entry point for running all management commands.

47

Here’s a draft PR for reading the config from pyproject.toml. It’s very early stages yet, I haven’t written tests or adapted it to where things should really be done in a native implementation.

48

Hello everyone,

It feels like the topic has become quite broad, with many different perspectives and ideas being shared. I’ve noticed that while people may disagree on certain parts of the proposal, there is also support for other aspects. To help move things forward, it would be really helpful to have a clearer summary of what’s been discussed so far, including who is in favor of which specific elements.

At this point, and from my POV, I think it might be valuable to have a more formalized proposal that outlines the key points of agreement and the suggested next steps. I would really appreciate seeing a DEP with a shepherd, though I understand there are different opinions on whether that’s the best route forward.

Regarding the related tickets, they are still marked as wontfix for now because I don’t feel that we have a clear consensus on “what” or an execution plan yet. With that in mind, and with my Fellow hat on, I’d like to kindly request four things:

  1. A summary of what would be the reduced proposal following the previous commentary. It would be great to have an outline of the key behavioral changes and how those would be rolled out, any necessary deprecations, as well as updates to documentation and translations.
  2. I would also request explicit justification when adding an extra way to do something that can already be achieved via an existing command, as multiple approaches could confuse users. This item refers to the django command as well as not having manage.py used in the project template but still having it available (I find this the most confusing of all, since there are gazillions tutorials out there using python manage.py).
  3. To move/open draft PRs against @ryanhiebert’s fork rather than against Django’s main repo, at least until the tickets are accepted and we have a clearer scope.
  4. Lastly, please please please could someone please explain what is the usage of django-admin right now other than for startproject that would justify the rename/alias? This would be providing a clear list of the use cases for django-admin where the pain/issues can be showcased.

Considering the imminent 5.2 feature freeze and the existing commitments for that release, I think it would make sense to target any changes related to this proposal for 6.0+ so we have sufficient time to plan and coordinate.

Thank you all for your contributions to this!

2 Likes
49

@nessita I’ve moved both PRs to my repo while we sort out next steps.

I think it would be wise to limit the scope for Right Now to just the new command name. I think that getting the new name merged need not be blocked on updating all the documentation, which is why that PR wasn’t marked as a draft.

For just the command, I think we have a broader consensus to move forward. By my counting, I see 13 yes with 2 no. The 2 no are notable as current and former fellows, while the yes seem like a more mixed group, but with a decent amount of current and former fellows, DSF board members, and steering council members chiming in.

Getting the documentation update done right is important and will take time to do correctly, but I don’t see a compelling reason to avoid adding the new name right away, and letting the broader documentation changes bake.

A few of the justifications for the change that I’ve seen in this thread are

  • simplifies use with uvx and pipx
  • a bit more fun, intuitive, generally easier to grok
  • easier to remember
  • intuitive and aesthetic

I think that you likely understand all of them, and have a different value judgement. That’s not only fine, it’s good. Our community is healthiest when we can express our disagreements and then take the actions we’ve agreed on together.

Would you want a DEP for this minimized proposal (to add the django command and update the documentation, in separately merged steps), to get formal approval for the plan? I don’t mind writing up a DEP, and generally making formalized steps more socially reasonable sounds good to me, but the boundary of DEPs is still pretty fuzzy to me and I’m not sure this is “big” enough for it, and I want to respect everyone’s time as much as possible.

The additional changes to add configuration defaults, update the startproject template, and use the newly expanded command across the documentation seem notable enough to me that even if we have a sense of rough consensus, that a DEP sounds like a nice idea to me.

50

@ryanhiebert I don’t think just ploughing on is the right way forward here. “Measure twice, cut once” is a useful maxim to keep in mind.

There are various valid points on all sides to make sure that are considered, and I’m not sure you have the count right on yays/nays. I think there are a few more qualified positions than you’ve credited, if I read the thread correctly.

Even so, resorting to bare votes should be a last (or much later) step. This conversation is only a few days old, and those days have been over the holidays, where only the very hard core even see any discussion at all. We’ve not given even a fair chance to seek a consensus, nor really thought through the concerns raised. (A good read on consensus seeking, since it’s relevant.)

Nothing is happening before the 5.2 feature freeze, so I suggest a period just cool down a notch. It’s not urgent.

The new @steering_council will be meeting soon, once the holidays wrap up. I’ll make sure we discuss this.

(Never tried it before: will enable slow mode for the weekend so we’re not just batting points back and forth, hopefully :crossed_fingers:)

2 Likes
51

Adding to Carton’s response, which I fully agree with, I would value it if concrete and detailed use cases could be provided, showing how the current django-admin is used outside of startproject and highlighting pain points or issues that could be resolved or mitigated with a django alias.

I believe the use cases are crucial for any subsequent decision-making, and I would appreciate it if they could be addressed as a dedicated comment in this post to avoid any confusion or dilution with other proposals or arguments.

52

I agree, we shouldn’t push this until we actually know what it’s going to look like. Otherwise it will lead to confusion, possible reversions and later changes of behaviour. It doesn’t seem worthwhile.

A DEP for this (1 and 3 to be specific, but with django-admin being the alias IMO) should not take too long to write. It’s a change to a longstanding feature so it’s probably justified. And having a document will provide clarity for what will actually happen. As it is the thread here is still quite confusing compared to what a single structured document would be.

I’d be happy to write a draft, shepherd it, or both. I probably wouldn’t have time for the actual implementation, just to set expectations.

1 Like
53

Before I respond in a dedicated comment to @nessita’s request to the best of my ability, I’d like to apologize for speaking about counts of informal “votes”. Like others have suggested, I was feeling that this topic needed to be explicitly narrowed for progress to continue and as the OP I felt that I had a particular duty to try to steer it that way. I wanted to give my impression of a reading of the room thus far on the narrower scope as a support for narrowing the scope explicitly, but I can see how it can easily come across as attempting to be coercive rather than informative. This was not my intent, and I’m sorry that what I said wasn’t in line with my intent or the values that I share with this community.

If any actual voting takes place at all, it won’t be arbitrary individuals votes that make the decision, it will the steering council, in the specified manner, which probably should be in a new thread rather than at the end of a longer discussion about a number of possible approaches. Thus, no matter what votes are counted or not, the only thing they can ever provide is an attempt at quantifying the temperature of the room, and it is virtually guaranteed to lose nuance, as has been noted in response to my counting.

Further, I believe that I did misread the room in suggesting that it seemed that there was similar support for narrowing it to only adding the alias. I’m finding more reason to doubt that people likely think that it is separable in this discussion from the broad work of updating the docs to prefer the new spelling.

Django seeks consensus, this is the right time for consensus building, and it takes active energy to do so. I’m sorry that I misdirected that energy. I’m still trying to figure out where my energy belongs in order to be most effective in appropriately pushing the process (not the people) to a conclusion (even one I don’t like) without my own inaction being a cause of undue delay.

54

I don’t currently use anything in the existing, unaugmented django-admin command except startproject, and I haven’t seen anyone in this thread say anything that suggests to me that they are thinking of any other usual use.

However, I do use the fact that the manage.py really is a thin wrapper around the django-admin command, and I leverage it to use (my own alias of) django-admin to replace manage.py in my own projects. I don’t want to expand the scope of the topic to that, other than to call out that it is already part of the interface of django-admin.

  1. uvx django doesn’t work, nor does uvx django-admin. The basic usage of uvx is not sufficient to use it to run startproject, you need to have a better understanding of both Django and uvx to find a correct alternative to run. The challenges with pipx are very similar to this.
  2. python -m django-admin doesn’t work. The docs are consistent in using django-admin, but if you wrap it in python -m, as has been similarly suggested for tools like python -m pip, etc, it doesn’t work.
  3. pip install django; django doesn’t work. Many other tools in Python follow this pattern. If you learn this pattern before you learn Django, you may try something intuitive and find that it doesn’t work, and then need to go to read the docs to figure out why you’re so incorrect that you don’t even get a help message on the CLI.

To be clear here, none of these indicate any DX catastrophe. I would classify this as a common paper cut, especially for newcomers. I value making new user experiences as seamless as possible, even over helpful (and intentionally inconsistent) maxims such as Python’s famous only one way to do it.

In this case, I suggest that it’s wisest to heed this zen by providing both spellings for backward compatibility and intuitive discovery (practicality beats purity), but being consistent in which one we document and encourage. Other people may have different judgements of how to most wisely apply the imprecise values from Python’s most famous poem.

55

I’m still inspecting my own motives, and even here I’m not sure that I’ve been honest with or about myself. I wasn’t intending to coerce, and in fact perhaps assuming too much that I’m unable to coerce, to the point of not even realizing that my words might seem coercive. But I wasn’t intending merely to inform as I implied here, I was also intending to push to see if the limited scope could be moved on more quickly. This is a tricky balance to get right, because while coercion is entirely inappropriate, clear and specific requests for targeted action are necessary to make effective progress.

I’m sorry that I misrepresented myself in my apology and undermined it. I want to be clear about what I have done wrong, so that I can be most effectively corrected if I’ve made other errors, and if I can’t be corrected that the community can know clearly when it will be appropriate to ask me to end my involvement.

56

Thank you so much for answering this specifically for the more limited scope. It seems like a DEP tends to imply a steering council vote, and I know we value consensus enough to try and avoid requiring action from those specific people, and I think that’s been my hesitation, as I’m trying to avoid requiring any specific action from anyone as much as possible (we’re all volunteers, after all).

I’m similarly willing to draft or collaborate on it, however is best. As you’ve mentioned, it shouldn’t be hard. I would greatly appreciate having you shepherd it.

57

The DEP process is confusing, but I think that SC involvement is not required unless consensus can’t be built based on the DEP.

1 Like
58

The DEP process is definitely not clear and I really want that to change. I would love to see the process become smoother and one way of doing that is clearly to create more DEPs, so please @ryanhiebert I’d love to see a DEP for this!

2 Likes
59

I completely agree with Emma that we want to see more DEPs and to make the process much easier. I also think that for this specific proposal, now is an excellent time to start summarizing the discussion in a DEP.

Finally, I want to say that as a Steering Council member I want people to feel they can actively ask for my involvement in their proposal. Personally, making the contribution process easier is my top goal for the 6.x cycle.

4 Likes
60

Thank you, Lily. I really appreciate that, and I think especially combined with doing our best to find ways to not get blocked on any person’s involvement, we’ll start to see where the rough edges are and can sand them down without just causing an overload on the steering council.

1 Like
61

I took a stab at writing a DEP. Thanks @tom and @jeff for your guidance and review.

4 Likes