Feature request: startproject and startapp should provide feedback

Django Internals
1

I’d like to propose adding a success message / feedback when running the startproject and startapp commands. For people who are experienced devs it might be expected that a successful script exists without any output. For beginners, it can be very confusing.

This shows up as an issue for people who go through Django tutorials, as django-admin and startproject are often their first point of contact with the framework after installing Django.

See for example:

From personal experience with Django Girls in particular, this is causing a common issue where people won’t realise the command has worked so will run it multiple times with different options (for example with or without a destination folder), which leads to at best confusing error messages, at worst multiple projects created within one-another.

Output options

As far as what success message / feedback to display, my personal recommendation would be to show a “success” one-liner, and then all files that were created with their folder structure, like a lot of tutorials do. For example the official tutorial shows:

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

The “success” one-liner would be a good first step – perhaps just restating the command arguments in the past tense (“Successfully created <project_name> at <project_path>”).

For example, Next.js has a great one-liner and then a good intro to available commands. Run:

npx create-next-app@latest nextjs-blog --use-npm --example "https://github.com/vercel/next-learn/tree/main/basics/learn-starter"

Output:

Success! Created nextjs-blog at /Users/thibaudcolas/Dev/djangogirls/nextjs-blog
Inside that directory, you can run several commands:

  npm run dev
    Starts the development server.

  npm run build
    Builds the app for production.

  npm start
    Runs the built app in production mode.

We suggest that you begin by typing:

  cd nextjs-blog
  npm run dev

startapp

For startapp, I would say the exact same applies where stating the command worked and showing the output would help with people’s understanding of what they are doing.

4 Likes
2

I think if we added[*] a matching -q/--quiet pair for the old-hands, this would be a great enhancement :+1: Update: since both @apollo13 and @adamchainz think this unnecessary, let’s forget the -q. (I’m too defensive in my old age :sweat_smile:)

[*]: Maybe the existing -v/--verbosity flags could be co-opted here, but I’d like to see that in a PR before committing one way or the other. :thinking:

3

I honestly don’t think that a quiet flag would be needed, one can simply ignore the output and that is not a command one uses often anyways. I for one usually don’t even use startapp at all and just create the files needed myself…

4

This is a great idea. A little green “success” message and the tree of files sounds brilliant. I’m not sure about the “further commands” section, it would depend a lot on the project template, output directory, and the settings files as to what would actually work.

Like Florian I also struggle to see the value in a quiet flag or low verbosity mode. People rarely start projects or apps. We don’t have a flag for disabling the default runserver page :man_shrugging:

1 Like
5

+1 from me.

If this is intended to help beginners, then like the Nextjs example, I would suggest that a reminder of helpful next steps would be good.

eg

  • startproject: manage.py runserver
  • startapp: update your settings (INSTALLED_APPS), the makemigrations/migrate commands
6

I also think this is nice to have. It goes without saying I suppose that it should reflect the template used.

I also agree with adding some useful info. I would add to @nanorepublica’s suggestion that I’m not so sure about migrations stuff as not every app has models these days. It might be a good reminder but maybe the reminder is too early if the user hasn’t created any models yet.

Some possibilities:

startproject

  • runserver - and link to the demo page
  • remind the user to create a custom user model (maybe point to docs)
  • migrate to create said user model and also other tables (contenttypes etc.)

startapp

  • don’t forget to add this to INSTALLED_APPS - not always necessary but not much harm in it
  • maybe there are others but my brain is broken
7

I’m +1 to the original proposal of showing a success message and displaying the layout of the created folders/files.

OTOH, I wouldn’t go that far in printing extra messages, such as links to docs or further steps, because:

  1. Is very difficult to guess/assume what’s the intent of the acting user, so polluting the output could be undesired, and
  2. The feature may get more complex and gaining consensus could (possibly) be less trivial, because of the need to agree on what to say and where to link the user.

I think that if we keep the scope small and specific, we can push forward this change and once it’s in, we could built on top of that.

8

Thanks all, I’ve opened #34976 Feature request: startproject and startapp should provide feedback based on discussions in this thread.

1 Like