Feature request: startproject and startapp should provide feedback

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.

6 Likes

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:

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…

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:

2 Likes

+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

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

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.

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

1 Like

We now have two PRs that seem quite solid and will effectively complete the ticket I created once merged:

This seems like quite a great improvement to me – so I think I’ll leave it there. But I do have one follow-up question for people here: would you expect the output of those commands to be featured in the docs?

I’d have naturally said “yes”, but of all 33-ish management commands documented on django-admin and manage.py, I see only one where the output is present.

Note for ref – the patch style docs say:

  • If the code associated with a patch adds a new feature, or modifies behavior of an existing feature, the patch should also contain documentation.

Good stuff. :gift:

Just on the the last, I’d think a release note would be enough. (For me, including the output isn’t necessary.)

I agree! And I have restarted efforts in having these merged. Both are “suffering” from similar errors when it comes to outputting unicode chars in Windows, so we are now seeking some assistance from Windows users. David Smith has already offered to help, but if anyone else is available to diagnose/fix issue, please see this comment and this comment.

I agree with Carlton that a release note would suffice, but we should also check/update tutorials and howtos showing the output of these commands.

Please can the Accessibility team (cc @tom, @sabderemane, @thibaudcolas - note: would love to be able to @ the accessibility team) re-review the tree structure proposal.

The tree structure might be unreadable for speech and braille.
If this is the case, I would be -1 for adding in the tree structure but keep the success message.

For those users, there are two separate aspects here – the semantics of the tree structure, and the characters we use to denote it for sighted users.

For the semantics of the tree structure, yes, it will be impossible to convey that for screen reader and braille display users short of spelling it out in english (“folder mysite contains manage.py”, “folder mysite contains mysite contains init.py”, etc). There are no semantics in command-line output to do this any other way like there would in HTML.

For the characters used to show the nesting (|___), then this will be announced as “vertical line underscore underscore underscore”. We should never use gratuitous ASCII art because it’s unintelligible and creates verboseness for those users. Here I don’t foresee 4 characters per line being a problem (it’s the same amount of verboseness as say __init__.py).


So – my accessibility team recommendation would be to keep the tree structure for the sighted users that will benefit from it. I don’t think 4 characters qualifies as a verboseness problem for screen reader and braille display users. We could reduce to two (|_) if we wanted to play it safe but I suspect it’s a non-issue.

I think we should also consider the amount that gets printed to the console.
When using a template, this can be a lot:

I think with that context in mind, and that this is unusable for some users, we should reconsider the quiet option.

I also think the Next.js example format would add more value to beginners:

Success! Created mysite at /some_path/mysite
Inside that directory, you can run several commands:

  python manage.py runserver
    Starts the development server.

  python manage.py migrate
    Updates your database schema.

  python manage.py createsuperuser
    Creates a superuser. This user can login to the admin.

We suggest that you begin by typing:

  cd mysite
  python manage.py runserver
2 Likes

From your example, yeah, I agree. Users can always use ls, tree, their IDE, etc to list files. Perhaps we could still report the number of files created though?

For “next steps” commands, we can’t rely on manage.py existing since the template may not have it. We can report python -m Django as the command if it does not exist, although then the settings module won’t be picked up without the end var or —settings… Hmm maybe only report commands when manage.py exists?

1 Like

A quiet option sounds good. I don’t think we should frame this as “either a list of files or a list of helpful commands”. We can complete the work on the success message and the files tree that’s already very far ahead, and if others want to add commands as well, that’ll be a very helpful addition.

In my opinion the length of the output isn’t super relevant, this is something users would run somewhere between once a year and once a week.