Revisiting the project root vs project_slug folder for creating apps

[hnarayanan]

Description

This issue is in the vein of #1725 and #3803, and discussions elsewhere e.g. https://stackoverflow.com/questions/39838290/is-there-a-command-for-creating-an-app-using-cookiecutter-django

The basic question is where is the canonical place to create an app?

• The most natural thing to do, ./manage.py startapp <app_name>, creates it at the root level which looks yucky.
• Moving it manually and tinkering with apps.py aesthetically looks nice (except the LOCAL_APPS in settings) but seems to not work in edge cases. e.g., I use a lot of Django's lazy loading of ForeignKey models (using strings) to avoid circular imports. In this situation I'm now forced to say project_slug.app_name.ModelName which is not an allowed thing to do.

My proposal is that we consider (the inner, as in not project root) {{cookiecutter.project_slug}} folder the root folder you'd get if you did django-admin.py startproject project_slug, and possibly even call it src.

Then you'd have something like:

{{cookiecutter.project_slug}}
├── compose
├── docs
├── locale
├── requirements
└── src
    ├── manage.py
    ├── app1
    ├── app2
    ├── {{cookiecutter.project_slug}}
    │   ├── config
    │   │   └── settings
    │   ├── contrib
    │   │   └── sites
    │   │       └── migrations
    │   ├── static
    │   │   ├── css
    │   │   ├── fonts
    │   │   ├── images
    │   │   │   └── favicons
    │   │   ├── js
    │   │   └── sass
    │   ├── templates
    │   │   ├── account
    │   │   ├── pages
    │   │   └── users
    │   └── utils
    └── users
        ├── api
        ├── migrations
        └── tests

In the above, the users app is no longer special, and doesn't need to be imported as {{cookiecutter.project_slug}}.users in the settings file. The config folder is also moved, but is perhaps not even necessary as it might be more vanilla Django to simply have.

└── src
    ├── manage.py
    ├── app1
    ├── app2
    ├── {{cookiecutter.project_slug}}
    │   ├── settings

I am a fan of this project and I try to use it and get caught up on this specific aspect of where to create an app every time I try. I would be willing to implement these proposed changes as an experiment if others agree with the general thought process.

[Brandl]

I agree with your overall assessment, but maybe there is another way? Would it be possible to hook manage.py or supply a custom management-command that gets it right?

[hnarayanan]

There might be. In one of the threads linked previously, it appears someone has tried and it is more work than it's worth. I have not tried myself.

But more philosophically, it feels like a lot of work to arrive at a structure that's not the same as an out of the box vanilla Django project.

[Brandl]

I found this pull request, that achieved this and got little attention thus far: #3358

Doesn't negate your point about structure, so happy to hear the opinion of others.

[hnarayanan]

Thank you for finding and sharing. This seems to do the right thing on the surface. I will try to fetch and play with it and see how it feels.

(Again not even sure about the original design decision that necessitates any of this.)

[browniebroke]

Highly subjective topic you're raising here 😊 so to sum up, the main problem is with startapp command?

I found this pull request, that achieved this and got little attention thus far: #3358

I'm a bit torn with that PR. I'll write some feedback there...

[hnarayanan]

It is really subjective, I know ☺️. I hope I am not being annoying. The main confusion is indeed with the startapp command, which by default plops apps in a different place from where users is. And it's not clear to someone (me) unfamiliar with the core design of this project where apps have to go.

[WoosterInitiative]

Every time I come back to this project I find myself rehashing the same issue. Why is there no documentation of where new apps should go? It's not immediately clear to me whether it should be in the true root or in the slug root. I always end up with them in the slug root, but it's neither entirely clear to a newcomer nor trivial to create apps that way.

Is there a reason that there isn't a section after the "Getting Up and Running..." about how to actually start developing the app? Or at least some reference (that's easy to find/discoverable) to how a project should be structured? I've spent a few hours every time I start a new project remembering how to make everything work and debugging the inevitable issues I come across.

I'm happy to do a PR, but I want to make sure there isn't a good reason this hasn't been done?

[browniebroke]

Is there a reason that there isn't a section after the "Getting Up and Running..." about how to actually start developing the app?

Not really, we could add it. That was explained here a bit more before your post, so it looks like it would be a welcome addition to the docs, yes. PR welcome.

[foarsitter]

A nice proposal I'm considering: https://david.guillot.me/en/posts/tech/proposal-for-a-django-project-template/?utm_campaign=Django%2BNewsletter&utm_medium=web&utm_source=Django_Newsletter_255#-project-structure