I recently worked on this ticket: Ticket #35546 to update the contribution pages to align with current requirements for tickets.
Following some of the comments I received on the PR, there is a suggestion to remove the “Non-trivial contributions” section since it was introduced 13 years ago and hasn’t really changed since.
This is the comment I am referring to:
In my opinion, this classification of “trivial” vs “non-trivial” within the same page makes the documentation harder to follow. Additionally, implying that “small bug fixes” are “trivial” can be discouraging for individuals who find them quite challenging to resolve.
What do people think about this? Should it be removed, or do we need to find a better way to phrase this?
I am leaning more towards implementing the changes suggested in the PR.
This is the link to the page in the documentation.
Thank you for raising this @Maryam and for your recent work improving our docs
Personally I would be comfortable removing the Non-trivial patches section, as I don’t believe it adds value in it’s current form.
If we don’t remove it, I would rebrand it away from the word trivial. Perhaps titled “Contributions which require wider discussion” and updating the content to something like:
A patch that introduces Django functionality and makes some sort of design decision requires a wider community discussion. Especially if the approach involves a deprecation or potentially introducing breaking changes.
Please include evidence that the approach and alternatives have been discussed on the Django Forum or django-developers list.
My gut on this section is that it should then be changed (and not removed). Sarah’s recent talk is probably a good starting point, especially the 3 types of tickets that exist in Trac (Bugs, New Features, Clean up/Optimizations).
This is also possibly a place to note that new features can and should be trialed in a third-party package before being proposed as an addition to Django core. Also as Sarah has mentioned the DEP process for larger new features.
Big +1 from me on better advertising the DEP process. There’s obviously a line between where just opening a ticket / forum post isn’t enough, and a DEP is needed, but I’m not especially clear on where that line is.
Whether that’s a self-titled section, or something closer to “Larger improvements to Django” I’m not sure. The gap between “Introduces Django functionality” and “Should have a DEP” is quite large, so anything we can do to clarify them is going to help.
In particular, some extra pointers on when a DEP makes sense, how to go from “It’d be cool if Django did X” to starting to write a DEP etc would probably make them feel less daunting to enthusiastic newcomers. Relying on @carltongibson to spot a discussion on Mastodon and push you in the right direction probably isn’t quite a sustainable and scalable process!
Trying to pull in some feedback for something concrete
Contributions which require community feedback
A patch that introduces Django functionality and makes some sort of design decision requires a wider community discussion. Especially if the approach involves a deprecation or potentially introducing breaking changes.
Here are a few approaches for gaining feedback from the community.
Django Forum or the django-developers mailing list
You should explain the need for the change, go into details of the approach and discuss alternatives. Please include a link to such discussions in your patch.
Third party package
Django does not accept experimental features. If you need user feedback on a public interface, landing this into Django core is not the way to do it. Iterations must follow the deprecation process and take months-years for the users to see the benefit of such changes.
Therefore, in such cases, it is better to create a third-party package which seeks user feedback. The public API can be iterated on and you can validate that there is a need for such a feature.
Once this package becomes stable and there are clear benefits of incorporating aspects into Django core, starting a discussion on the Django Forum or the django-developers mailing list would be the next step.
Django Enhancement Proposal (DEP)
Similar to Python’s PEPs, Django has Django Enhancement Proposals or DEPs. A DEP is a design document providing information to the Django community, or describing a new feature or process for Django. DEPs provide concise technical specifications of features, along with rationales.
DEPs are the primary mechanisms for proposing major new features, for collecting community input on issues, and for documenting design decisions that have gone into Django.
Once the DEP is ready, the Steering Council votes on whether to accept it.
Or something something @Maryam I guess maybe give something a go and then link the PR to this discussion and then anyone who is interested can make concrete suggestion on the wording and content
@sarahboyce I have created a draft PR to give it a go and see if the changes are fine.
I still left the Typo fixes and trivial documentation changes section. Do you think I should remove it since we have a more detailed section on patches?
We should keep the Typo fixes and trivial documentation changes section as this is about when you don’t need a ticket (really tiny things) and you don’t need to discuss the change with the community.
This section you’re working on is about when you need to discuss stuff
