Proposal: add officially endorsed packages to Django docs

There have been discussions recently, both on the Django email lists and at DjangoCon US, about having Django officially endorse some set of third party libraries that provide functionality not in the framework itself.

This should at a minimum go on the docs home page.

These could also be linked to from other pages where relevant, with a call-out that this is a third party package.

There are two categories of libraries that I would like to propose for initial inclusion:

  1. Django API frameworks, such as:
  • django-rest-framework
  • django-ninja
  • graphne-django
  1. Django utilities (things that augment core pieces of Django), such as:
  • django-crispy-forms
  • django-storages
  • django-extensions
  • django-environ
  • django-debug-toolbar

The above libraries are my personal suggestions. Library maintainers should be consulted before their library is included to make sure they are ready for the likely increase in traffic that would come from such an official endorsement.

The list should probably conclude with a link to Django Packages, with the caveat that Django does not officially endorse all of the things listed on Django Packages.


Example of a docs call-out for a third party library:

+1 on this.

Bikeshedding, but not to detract from my +1: There may be another place for this: External packages | Django documentation | Django, with a reference to it on the home page. I think that may allow more “space” on the page to add some brief information about the packages or categories without adding to (what I think may be) an already-crowded page.

Also agree on the link to with the stated caveat that it is an uncurated list.

I’m keen on something here, but we probably need @steering_council oversight.

Django has historically not linked to third party resources (simply because it’s hard to keep updated I’d guess)

For 4.2 we added a tutorial step linking to Django Packages and Django Debug Toolbar, but even for that (which is one of Django’s longest standing packages) and even with discussions at DjangoCon and online there was significant push back (and I personally had to burn quite a lot of social capital to push it through as one of my last acts as a Fellow).

I imagine a good story about how we keep it maintained and how we decide which qualify would salve many concerns.

How we keep it maintained - serious question since I don’t know - how do we keep the docs maintained through every release? It seems to me that there’s already a significant effort to ensure that the docs are properly maintained (yea Django!), and I can’t imagine that for the types of packages I would envision being listed that there would be any sort of churn on the list.

And that leads to the second question - what qualifies? From what I remember of the conversations at DjangoCon and just tossing around ideas, I would think the criteria would need to include something like a substantial history of Django support (e.g. 5 years-ish), along with being highly regarded by a significant percentage of the DSF membership with few detractors, and among the most popular “N” number of packages. (I would have no problem setting some kind of upper limit in terms of numbers of packages allowed to be listed - but there could be fewer.)

I’m envisioning something like the annual Django developers survey, but more targeted to this specific issue, and allowing people to rank their choices. (Not just pick 5, but list in order what the 5 or 10 most important third-party packages are for you.)

There was definitely a lot of discussion about this at DjangoCon US this year - I am personally in favour of the idea, provided we can some up with some reasonably scalable way to decide exactly what we put into that list. In many ways, I would expect it to end up as a lighter set of rules compared to what used to be applied to put things in Django itself.

One point I did want to make is that pointing people towards packages officially will most likely put an extra burden on those packages in terms of support and issues being filed; I would love to find a way to extend, say, the Django security response process to some top tier of recommended packages, to help both users have more confidence and maintainers know that being recommended also comes with some help.

As for the steering council’s involvement - I don’t think this has any official remit there, and I’m not sure how I feel about adding it in, especially given that I think the steering council needs its own work to define what it is, and if it even exists in the same form, in this era of Django.

There are two final thoughts I’d like to add:

First, I have answered a couple questions here where the topic got into the suitability or appropriateness of using third party packages. (Relatively few, maybe only 3 or 4.) Providing “official recognition” for some of the key packages may highlight the fact that one of Django’s key strength is the quality of those packages - and by extension, that there are other such packages worth investigating.

Second, when new ideas are proposed, the general recommendation has been “make it a third-party package” to see whether it gains traction.

But, what is the criteria to identify when it has gained sufficient traction to (theoretically) be considered for addition to core? There doesn’t seem to be any roadmap or guidelines for doing so.

Giving official recognition to these packages would seem to be an intermediate step.

(And to Andrew’s point, I agree that any official recognition should be done with the cooperation and approval of the primary maintainer of that project.)

(Note: I’m not saying that every sufficiently-popular package would be considered for being brought into core, just that it has reached some degree of stability and renown to be considered eligible for such.)

I meant that the Steering Council should explicitly endorse this change if it’s going to happen. Linking to external resources would be a change in a long standing policy, and there will be push back. Implementers and mergers could do with the protection of an official decision to point to.

I like the idea of linking to some packages, as long as we have clear rules for what qualifies. I would hope we can primarily follow community popularity. Maybe we can use the annual survey data.

We should be careful wording-wise. @zags ’s screenshot calls the packages “some that Django officially endorses” , which is too strong. Something like “Here are the most popular packages in the Django survey” would make fewer promises and cites a specific group of people (survey respondents) rather than “Django” (which means… the DSF? fellows? …).

I think this is because it really does depend on the size and divisiveness of the proposal. Adding an “official recognition” step could slow down smaller merges, or amount to box-ticking.

Take django-testdata, which improved TestCase.setUpTestData. It was merged into Django core without much popularity and with input from only a few people. But the package proved the concept and allowed testing it on multiple projects before committing to the approach in slower-moving Django core.