Hello Thomas, Thanks for bringing this up. There’s definitely some room for improving the documentation — I know because I wrote it.
In terms of organization, I’d rather discuss how each topic (settings, models, etc.) relates to projects and apps than talk first about projects, then about apps. Otherwise there’s some repetition between the two sections and it’s harder to compare. Your proposal touches many topics and was a good base for brainstorming. My thoughts below. > Project > ====== > A project is a container for apps. => Yes. > It contains only settings, no database models. => It’s also considered a good practice to put templates and static files at the project level (rather than spread across apps, even though Django supports it for pluggable applications. I would focus on saying that “models can only live within applications”. It’s part of the design of the ORM. > Since it contains no database models it does not contain database schema > migrations. > It can contain migrations which fill a database with project specific data. => You’re going to confuse people to no end if you evoke MIGRATION_MODULES, a highly advanced and tricky concept, in an introductory document. I wouldn’t discuss migrations at all here. Stick with models. => You could say something about fixtures, which can live either at the project or app level. However the argument for putting them at project level is as strong as for templates and static files. I’m not sure you could say something sufficiently clear to enlighten readers. > It is common that there is only one production installation of one project. => You could also say that a project often corresponds to a website. > It is common to have several stages (dev, test, prod) for one project. => I usually say “environment”, not “stage”. > A project might contain a sitecustomize.py => There’s a consensus for saying that this is an uncommon technique in the Django world, albeit a legitimate one. Better not mention it in an introduction. > App > === > An app can have models, views and code. => And plenty of other things :-) migrations, translations, URLs, templates, template tags, static files, etc. > It should be re-usable. => I’d rather say “As much as possible, it should encapsulate an aspect of a project. Some apps are reusable, which means they can be shared between various projects. Reusable apps, sometimes called pluggable apps, are the most common way to distribute Django-related libraries." > An app can depend on other apps. > It must not depend on a project. => Technically, almost every app depends on a project in the sense that they require proper configuration of the project. This needs careful wording to avoid confusion. > An app can contain a settings.py for testing, but it contains no settings on > its own. => This is correct but I’m not sure it’ll be useful to people who have barely heard about reusable apps or unit testing, let alone how both interact with Django’s requirement to have a global settings module. They are the people an introduction to project vs. app targets. I would skip this topic. > It should have instructions which settings are needed to get the app running > in a project. => Yes. This goes with the discussion of how projects depend on apps. > A app must not contain a sitecustomize.py. => As above. This is not as easy to explain as it might seem for someone familiar with the concept… I hope this helps putting together a patch! I’m happy to review or further discuss a proposal. Best regards, -- Aymeric. > On 19 nov. 2015, at 10:54, guettli <guettl...@thomas-guettler.de> wrote: > > I created a ticket to find a better definition of "Project" vs "App" > > https://code.djangoproject.com/ticket/25748 > > I am happy since Tim Graham accepted it. > > Here are the current docs: > https://docs.djangoproject.com/en/1.8/ref/applications/#projects-and-applications > > Here is my view of Project" vs "App". It would be nice to find a consensus > and update the docs. > > Project > ====== > A project is a container for apps. > It contains only settings, no database models. > Since it contains no database models it does not contain database schema > migrations. > It can contain migrations which fill a database with project specific data. > It is common that there is only one production installation of one project. > It is common to have several stages (dev, test, prod) for one project. > A project might contain a sitecustomize.py > > App > === > An app can have models, views and code. > It should be re-usable. > An app can depend on other apps. > It must not depend on a project. > An app can contain a settings.py for testing, but it contains no settings on > its own. > It should have instructions which settings are needed to get the app running > in a project. > A app must not contain a sitecustomize.py. > > -- > You received this message because you are subscribed to the Google Groups > "Django developers (Contributions to Django itself)" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to django-developers+unsubscr...@googlegroups.com > <mailto:django-developers+unsubscr...@googlegroups.com>. > To post to this group, send email to django-developers@googlegroups.com > <mailto:django-developers@googlegroups.com>. > Visit this group at http://groups.google.com/group/django-developers > <http://groups.google.com/group/django-developers>. > To view this discussion on the web visit > https://groups.google.com/d/msgid/django-developers/1a7e8d69-1970-4b07-b820-90c4d652486b%40googlegroups.com > > <https://groups.google.com/d/msgid/django-developers/1a7e8d69-1970-4b07-b820-90c4d652486b%40googlegroups.com?utm_medium=email&utm_source=footer>. > For more options, visit https://groups.google.com/d/optout > <https://groups.google.com/d/optout>. -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at http://groups.google.com/group/django-developers. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/F567F34D-B3A1-4674-BD9A-6415663B5867%40polytechnique.org. For more options, visit https://groups.google.com/d/optout.
