DEP 15: Improved startproject interface¶

DEP:: 15
Author:: Tom Carrick
Implementation Team:: Tom Carrick
Shepherd:: Carlton Gibson
Status:: Accepted
Type:: Feature
Created:: 2024-10-26
Last-Modified:: 2024-10-26

Abstract ¶

The current method of starting a new Django project involves running the startproject and startapp commands, which creates a project with multiple folders. This structure can be confusing to new users. This DEP proposes a new structure for the startproject command that includes an app by default. Additionally, a new command will be added to provide a multiple choice interface for setting up a new project using various useful templates.

Further, documentation improvements will be made to use this new structure and explain how to create new apps within the project.

Specification ¶

Currently, the startproject command creates a project with the following structure:

.
├── manage.py
└── myproject
   ├── __init__.py
   ├── asgi.py
   ├── settings.py
   ├── urls.py
   └── wsgi.py

To get a working app, it’s then necessary to run startapp, which results in:

.
├── manage.py
├── myapp
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── migrations
│   │   └── __init__.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
└── myproject
   ├── __init__.py
   ├── asgi.py
   ├── settings.py
   ├── urls.py
   └── wsgi.py

This DEP proposes that Django should include a template to be able to create a project with an app pre-installed. The new structure would look like this:

.
├── manage.py
└── myproject
   ├── __init__.py
   ├── admin.py
   ├── apps.py
   ├── asgi.py
   ├── migrations
   │   └── __init__.py
   ├── models.py
   ├── settings.py
   ├── tests.py
   ├── urls.py
   ├── views.py
   └── wsgi.py

The settings.py file will be updated to include the project directory in INSTALLED_APPS.

A new command called new will be added to provide a user friendly interface for setting up a new project. This command may be a frontend of startproject.

The current tutorial could then be updated to use this new command and structure.

The initial templates proposed are:

The structure above, with a combined project and app directory. This will be the default for the new command, but not for startproject for backwards compatibility.
A minimal single file project for quick prototyping and testing. This might be especially useful for contributors.
A template suitable for writing a third party app.
A “classic” project structure using the current startproject template.

A URL can also be entered that works the same way as startproject.

If --noinput is passed to the command, it will select the default template.

This command could be extended later either by contributions to Django or perhaps by third party packages.

Motivation ¶

This proposal helps solve multiple problems currently encountered by Django users.

New user experience ¶

New users often struggle to get off the ground when following the tutorial. Two known sticking points are:

Confusion around having multiple folders.
Confusion around having two urls.py files.

It is also expected that by removing a step, the tutorial will be easier and faster to follow. This also has implications for improving other unofficial tutorials such as the Django Girls tutorial used in their workshops.

Contributors ¶

Contributors often need to set up a new project to test their changes. It’s not really documented anywhere how to do this, so there is no standard process. This can be a barrier to entry for new contributors. Examples of current methods include:

Using a project using models from the test suite.
The user maintains their own test project that expands over time.
Spinning up a fresh project each time.
Using a ready built site such as django-admin-demo.
Using one of the various single file templates from the web.

Of these, this proposal makes 3 and 4 easier, and 5 unnecessary as the single file project will always work with the current branch.

Third party apps ¶

Setting up a third party app can be quite complex. Something as simple as running tests or the makemigrations command can be quite tricky to figure out.

Developers ¶

Developers also benefit from this proposal as they get to a working state faster. They are still free to choose any layout they prefer, but by modernizing the default template it is hoped that projects will become more consistent and easier for people to find their way around.

Rationale ¶

Another way to do this could be to modify the existing template. However, this would cause some disruption to the community. Some people like the existing template, and third party tutorials such as Django Girls would need to be updated.

Simply adding a new template without a new command was also considered, but this makes it more difficult for people to find and use the new template. It also allows us to create a new default template, while still using the old template for startproject for backwards compatibility.

Another benefit of this solution is that it will set a precedent for adding new templates into Django. This could be useful for other templates such as a more complete setup for a REST API, or a project with useful frontend components. This would allow Django to have a supported and suggested way to integrate a frontend framework without being tied to a single framework. However there are a lot of risks involved with this, so it is not proposed here.

Django Enhancement Proposals

Navigation

Related Topics