Updating the default startapp template

I was on the fence for this one but after reading the newer comments, I’m +1 to make this change.
I’ve personally been puzzled a few times by the absence of a per-app urls.py, and I believe adding it by default will benefit both new and experienced Django users.



Could we make a decision on this one? I’d like to provide a resolution to the original author and in the PR.

There is a valid point in that a Django app without urls.py is completely valid, but I also agree with the counterargument that we are shipping the default app template with a views.py file which, following the recommended best practices, should be accompanied by a urls.py exposing the app-specific urls served by those views. So, in summary, it feels inconsistent to create a views.py by default and not an per-app urls.py.

Is also worth noting that existing tutorials and docs stating “…and then you should create a per-app urls.py file” would not need immediate fixing since people following the tutorials would find out that the file is already there and with a minimal (and useful) skeleton, so there shouldn’t be any surprises or confusion.

@tom to your point of “But I think it’s more likely they still would have been confused.”, and adding to what @czue already said, I’m confident that new comers would be less surprised by the file being there (based on teaching experience), but also, having the urls.py next to views.py would, if anything by using it mechanically, enforce the desired patterns for app isolation.

I personally think that the presented rationale (from the author and others in this thread) is strong enough to pursue this proposal, but since what is consensus is currently being (re)discussed and we have no concrete conclusion yet, ideally I’d like us all to reach a collective decision before proceeding any further (even if the decision is to not do this at this time).

Thank you!


I guess the problem for beginners is getting confused why they need (or don’t) two urls.py files.

The official tutorial and the Django Girls tutorial both create urls.py files. I notice two things:

  1. We often want a urls.py, in an app for beginners
  2. At this point in the tutorial, the user is prompted to create one.

I think the confusion here often comes from the urls.py not being explained. The official tutorial doesn’t do a good job of explaining why we do this. The Django Girls tutorial does a better, but still maybe not great job, but probably good enough if we don’t want to make the explanation too complex for beginners, either (we also have just a day to get through as much of the tutorial as possible, so brevity is also good!).

So I wonder then, if there isn’t value to be had by explaining why the urls.py file is there. Does this mean we need to make the user add it themself? Probably not.

I am a bit more convinced, maybe +0, but I feel it’s hard to make the right call here as we’re operating mostly on our educated opinions more than anything else.

The other option perhaps is to not promote such “app based development” so early in a beginner’s journey and rather go with a simpler project structure where the initial app uses the root urlconf and so, but there is already another discussion on the project template. There is so much crossover between the two it might be hard to make a decision on one without also considering the other.

I’m +1 on this change. While some people choose not to use app-specific urls.py files, the Django documentation and tutorials recommend them, so let’s treat them as the default here too.


I’m +/-0 but can I just suggest that if we start going down the path of adding more optional files can we print some output of the files generated in a tree like output along with annotations of required vs optional files? Something like the conversation we’re having with makmigrations output with colour & symbols.

I saw the post about stale PRs, which reminded me of this thread. Automatically marking stale PRs as such

As best I can tell there is still generally broad support for the change of making a simple urls.py file part of the default startapp template. I - admitting some bias - think there have been several strong arguments made in favor of doing it, and no significant arguments as to why not to do it.

I recognize that if we do nothing, the default path forward will be that the PR gets marked stale, this thread goes quiet, and then we have the conversation another 2-3 years in the future when the next person decides to bring it up. This makes me a bit sad, and would love to either explicitly get it in or decide not to, if someone can make a compelling case for that decision. Is there any way to make that happen?

Hi Cory :wave: a number of us are trying to think about how we can improve the “get to a decision” experience. To me, having a clear “no” is better than having energy pulled to a discussion over a very extended period of time (months/years).

Please add your experience to this forum discussion: Updating our DEP process / DEP 1.

Personally based on Forum: Django New Project Structure/Name and Refs #33650: Changes to the startproject template #15609, I’d recommend you ask the Steering Council “is this thread enough consensus or does this require a DEP”.

It might sound silly to write a formal proposal/spec for something that looks like an obvious own-goal, but at least it’ll be a straightforward proposal / spec. And as a specification with a pull request, everyone will get to spend as much time assessing all of the reasoning and every line of the proposed urls.py as they want.

It’ll also be a good opportunity to back up any opinions with more evidence, in a format that’s easier for people to follow than drawn-out forum posts and 17 years of discussion history. For example by citing existing tutorials like you have.

Based on conversation with Cory on the DEP 1 thread, I will just add another view, which hadn’t been expressed explicitly.

I don’t think it’s a big thing one way or the other, I don’t think it’s going to make any real difference to anyone. So that would be +/-0. Nonetheless, making the change requires rewriting tutorials, and such, all over the ecosystem. The cost of that, for me, makes it swing to -1.

The guiding principle is avoiding seemingly small changes, that have wide effect, unless there’s a real benefit. I’ll grant I lean to that, but then I’ve had in the ear so many times from angry folks pushing back when we’ve done such things in the past, that perhaps I bear the scars. :stuck_out_tongue_winking_eye:

Qua the +/-0 feeling, I’m not going to be upset if it goes the other way. I’m only posting because Cory said that maybe I should.:christmas_tree:

What does this process look like?

Thanks for raising this point, and I’d love to debate it. To be explicit, I think there are two separate questions:

  1. Is the change an improvement? I think nearly everyone, including you(?), is saying “yes” (that is, if we didn’t have any baggage and were designing startapp today, it would include a urls.py file).
  2. Is the change worth the effort? This is the question I think you’re saying “no” to now.

To make the case for “yes” on #2 I will say a few things:

  • The process of updating a tutorial is a one-time thing. Yes, it’s annoying, but it will probably take all of, what, 10 minutes? I’m happy to volunteer to update the official one if we decide to change this.
  • Once the tutorial is updated, everything is better forever. Whereas every time someone struggles with urls.py that’s creating work that will never stop if we never change it. So while it feels like we are creating work, in the long term we are actually reducing it.
  • If a tutorial (or whatever else) doesn’t get updated, and someone goes to add the file and it’s already there, that is a totally fine failure mode and not a big problem.

Given all that, I still think it’s worth it, even though it creates a small amount of additional short-term work to do.

I’m happy to volunteer to update the MDN and Django Girls tutorials.

@czue I believe you can ping the steering council with @steering_counil on the forum. “Hi @steering_council, could you take a look at this and comment on whether you think we should proceed with a DEP?”

If that doesn’t work for some reason, I’d ping the individuals listed on the DSF Teams page via their individual forum accounts.

Exactly. I don’t think we should worry about existing tutorials” because of this.

IMO this change is way too small for a DEP, writing one would just set a bad precedent and look silly to outside observers.

1 Like

We should add this +1