From 9f0abc1bfc496b72b2a5dd7811b983488eac158c Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sat, 26 Oct 2024 16:23:05 +0200 Subject: [PATCH 1/8] Add draft for extended project template --- draft/0015-extended-startproject.rst | 142 +++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 draft/0015-extended-startproject.rst diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst new file mode 100644 index 00000000..d835ce86 --- /dev/null +++ b/draft/0015-extended-startproject.rst @@ -0,0 +1,142 @@ +====================================== +DEP 15: Extended startproject template +====================================== + +:DEP: 15 +:Author: Tom Carrick +:Implementation Team: Tom Carrick +:Shepherd: Carlton Gibson +:Status: Draft +:Type: Feature +:Created: 2024-10-26 +:Last-Modified: 2024-10-26 + +.. contents:: Table of Contents + :depth: 3 + :local: + +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. + +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: + +.. code-block:: + + . + ├── 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: + +.. code-block:: + + . + ├── 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: + +.. code-block:: + + . + ├── 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``. + +The current tutorial could then be updated to use this new structure. + +Motivation +========== + +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. + +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. + +The proposed solution also has drawbacks however, in that there will be +duplication between the two templates. To mitigate this, the existing template +could be deprecated over some time period. + +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 +single file project for quick prototyping. + +Relevant discussions +-------------------- + +- `Django New Project Structure/Name `_ +- `Updating the default startapp template `_ +- `Update startproject with default login/signup/logout options `_ +- `The Single Folder Django Project Layout `_ + +Reference Implementation +======================== + +TODO. + +Copyright +========= + +This document has been placed in the public domain per the Creative Commons +CC0 1.0 Universal license (http://creativecommons.org/publicdomain/zero/1.0/deed). From 1dde401b7b0abf236fcd531c67da632fc1d109ab Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sat, 2 Nov 2024 11:07:50 +0100 Subject: [PATCH 2/8] Switch to new command --- draft/0015-extended-startproject.rst | 100 ++++++++++++++++++++++----- 1 file changed, 83 insertions(+), 17 deletions(-) diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst index d835ce86..182ade97 100644 --- a/draft/0015-extended-startproject.rst +++ b/draft/0015-extended-startproject.rst @@ -1,6 +1,6 @@ -====================================== -DEP 15: Extended startproject template -====================================== +======================================= +DEP 15: Improved startproject interface +======================================= :DEP: 15 :Author: Tom Carrick @@ -22,7 +22,9 @@ 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. +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. @@ -44,7 +46,8 @@ structure: ├── urls.py └── wsgi.py -To get a working app, it's then necessary to run ``startapp``, which results in: +To get a working app, it's then necessary to run ``startapp``, which results +in: .. code-block:: @@ -91,21 +94,79 @@ project with an app pre-installed. The new structure would look like this: The ``settings.py`` file will be updated to include the project directory in ``INSTALLED_APPS``. -The current tutorial could then be updated to use this new structure. +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: +1. The structure above, with a single app. This will be the default for the + ``new`` command, but not for ``startproject`` for backwards compatibility. +2. A minimal single file project for quick prototyping and testing. This might + be especially useful for contributors. +3. A template suitable for writing a third party app. +4. 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. +* 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: + +1. Using a project using models from the test suite. +2. The user maintains their own test project that expands over time. +3. Spinning up a fresh project each time. +4. Using a ready built site such as ``django-admind-demo``. +5. 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 default +structure will be faster to spin up and get working with, and 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 ========= @@ -114,21 +175,26 @@ 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. -The proposed solution also has drawbacks however, in that there will be -duplication between the two templates. To mitigate this, the existing template -could be deprecated over some time period. +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 -single file project for quick prototyping. +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. Relevant discussions --------------------- +==================== -- `Django New Project Structure/Name `_ -- `Updating the default startapp template `_ -- `Update startproject with default login/signup/logout options `_ -- `The Single Folder Django Project Layout `_ +* `Django New Project Structure/Name `_ +* `Updating the default startapp template `_ +* `Update startproject with default login/signup/logout options `_ +* `The Single Folder Django Project Layout `_ Reference Implementation ======================== From 576b83a24de4a10060f2983dbc96ab6fbe357542 Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sat, 2 Nov 2024 16:07:18 +0100 Subject: [PATCH 3/8] Clarify wording --- draft/0015-extended-startproject.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst index 182ade97..d367af1e 100644 --- a/draft/0015-extended-startproject.rst +++ b/draft/0015-extended-startproject.rst @@ -101,12 +101,13 @@ The current tutorial could then be updated to use this new command and structure. The initial templates proposed are: -1. The structure above, with a single app. This will be the default for the - ``new`` command, but not for ``startproject`` for backwards compatibility. -2. A minimal single file project for quick prototyping and testing. This might +1. 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. +1. A minimal single file project for quick prototyping and testing. This might be especially useful for contributors. -3. A template suitable for writing a third party app. -4. A "classic" project structure using the current ``startproject`` template. +1. A template suitable for writing a third party app. +2. A "classic" project structure using the current ``startproject`` template. A URL can also be entered that works the same way as ``startproject``. From 1999668065a40aee2f7da3683daa9890b949a38f Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sat, 2 Nov 2024 16:17:04 +0100 Subject: [PATCH 4/8] ??? --- draft/0015-extended-startproject.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst index d367af1e..5471c31e 100644 --- a/draft/0015-extended-startproject.rst +++ b/draft/0015-extended-startproject.rst @@ -104,10 +104,10 @@ The initial templates proposed are: 1. 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. -1. A minimal single file project for quick prototyping and testing. This might +2. A minimal single file project for quick prototyping and testing. This might be especially useful for contributors. -1. A template suitable for writing a third party app. -2. A "classic" project structure using the current ``startproject`` template. +3. A template suitable for writing a third party app. +4. A "classic" project structure using the current ``startproject`` template. A URL can also be entered that works the same way as ``startproject``. From c697c8aa87c546f15af8ba6440ba9e8dcc6d2d6c Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sat, 2 Nov 2024 16:18:01 +0100 Subject: [PATCH 5/8] More fixing --- draft/0015-extended-startproject.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst index 5471c31e..ad848bcb 100644 --- a/draft/0015-extended-startproject.rst +++ b/draft/0015-extended-startproject.rst @@ -102,13 +102,14 @@ structure. The initial templates proposed are: 1. 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. + the default for the ``new`` command, but not for ``startproject`` for + backwards compatibility. 2. A minimal single file project for quick prototyping and testing. This might - be especially useful for contributors. + be especially useful for contributors. 3. A template suitable for writing a third party app. 4. 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. From f95f6210b8f0a0f3743960b26cd4301a777e59c4 Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sat, 2 Nov 2024 16:18:57 +0100 Subject: [PATCH 6/8] okay one more --- draft/0015-extended-startproject.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst index ad848bcb..3eb30197 100644 --- a/draft/0015-extended-startproject.rst +++ b/draft/0015-extended-startproject.rst @@ -101,6 +101,7 @@ The current tutorial could then be updated to use this new command and structure. The initial templates proposed are: + 1. 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. From 2418930db6083841921f3c26178dfdab20154f7e Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sun, 3 Nov 2024 16:18:17 +0100 Subject: [PATCH 7/8] Update draft/0015-extended-startproject.rst Co-authored-by: Shai Berger --- draft/0015-extended-startproject.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst index 3eb30197..eb2be426 100644 --- a/draft/0015-extended-startproject.rst +++ b/draft/0015-extended-startproject.rst @@ -198,7 +198,7 @@ Relevant discussions * `Updating the default startapp template `_ * `Update startproject with default login/signup/logout options `_ * `The Single Folder Django Project Layout `_ - +* `Why do we need apps? `_ Reference Implementation ======================== From 603825700cd0ea29060dbfcd846767f952e84a1b Mon Sep 17 00:00:00 2001 From: Tom Carrick Date: Sat, 9 Nov 2024 11:24:56 +0100 Subject: [PATCH 8/8] Add reference implementation --- draft/0015-extended-startproject.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/draft/0015-extended-startproject.rst b/draft/0015-extended-startproject.rst index eb2be426..c3eec750 100644 --- a/draft/0015-extended-startproject.rst +++ b/draft/0015-extended-startproject.rst @@ -199,10 +199,11 @@ Relevant discussions * `Update startproject with default login/signup/logout options `_ * `The Single Folder Django Project Layout `_ * `Why do we need apps? `_ + Reference Implementation ======================== -TODO. +https://github.com/knyghty/django-new Copyright =========