-
-
Notifications
You must be signed in to change notification settings - Fork 31.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Tutorial 02 Database Setup Documentation update #18253
base: main
Are you sure you want to change the base?
Conversation
… not relevant to the tutorial and can be found elsewhere in the documentation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hello! Thank you for your contribution 💪
As it's your first contribution be sure to check out the patch review checklist.
If you're fixing a ticket from Trac make sure to set the "Has patch" flag and include a link to this PR in the ticket!
If you have any design or process questions then you can ask in the Django forum.
Welcome aboard ⛵️!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The documentation clean-up looks good to me - but there are some unwanted toast-related changes in there too!
Deleted information on "make toast"
Deleted test_make_toast.py
deleted notes on make_toast function
deleted make_toast() function
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I deleted all references to the "make_toast()" function that were accidentally included in this PR.
@evildmp, there should be no more traces of "toast" now! |
As the author of many third-party database backends, I'm -1 on removing this. It's perfectly reasonable that newcomers to Django may not want to use SQLite. I don't think it's much of a burden for people to skip this section if it's not relevant to them. |
In a tutorial we should not be including material that users might want to skip, and definitely not be including material that the vast majority of users will want to skip. In ~12 years of running introductory Django workshops and working with hundreds of beginners, I don't believe I have ever seen someone opt to use anything but SQLite. If someone is interested in using another database, they are very unlikely to want to know about it at this stage, because this is not a tutorial about Django and databases but about basic concepts in Django. That material, however important, belongs elsewhere and not here. It's not just a burden on the user, it's also a burden on the maintainer. The tutorial needs to be a bullet-proof experience in which we take responsibility for the users' success, which we can only do if we know what's going on. If we introduce options, we have to take responsibility for guaranteeing success in all those different pathways. It's a reasonable contract with the user to say: if you want to learn Django, follow our directions, so that we can help you. SQLite is built-in and doesn't require anything more. |
docs/intro/tutorial02.txt
Outdated
@@ -24,42 +24,6 @@ database. When starting your first real project, however, you may want to use a | |||
more scalable database like PostgreSQL, to avoid database-switching headaches | |||
down the road. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would end this paragraph something like:
... down the road (see the database settings reference https://docs.djangoproject.com/en/5.0/ref/settings/#databases for more information).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've included another sentence with links at the end; let me know how this looks @evildmp @timgraham
I don't feel the audience of the tutorial should be limited to introductory Django workshops. I'm sure there are plenty of users who are new to Django and want to use it with their favorite database. |
I have added a sentence at the end with links to 'database installation' and 'database settings' for anyone who would like more information about it.
I deleted some leftover text which was not needed.
Completely agree! But a tutorial is not the place for this. The tutorial should by all means contain pointers to such information, where the people who would benefit from it will find it, without making the vast majority of the people have to think about whether it applies to them. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks good to me. @nessita your thoughts?
Trac ticket number
N/A
Branch description
I removed some unnecessary text about setting up a different database than the default SQLite to prevent overwhelming new Django users. This information can be found in more relevant parts of the documentation when the user is ready to experiment with different databases.