Opened 3 years ago

Closed 3 years ago

#21609 closed Bug (fixed)

CONTRIBUTING.rst contradicts the contributing guidelines

Reported by: Chris Jerdonek Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Chris Jerdonek Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no


The Django documentation gives contradictory guidance on how to submit a trivial doc fix. CONTRIBUTING.rst says:

Warning: pull requests are ignored! File a ticket to suggest changes. ... Patches can be submitted as pull requests, but if you don't file a ticket, it's unlikely that we'll notice your contribution.

However, Submitting patches says,

If you are fixing a really trivial issue, for example changing a word in the documentation, the preferred way to provide the patch is using GitHub pull requests without a Trac ticket.

Change History (8)

comment:1 Changed 3 years ago by Baptiste Mispelon

Needs documentation: unset
Needs tests: unset
Patch needs improvement: unset
Triage Stage: UnreviewedAccepted

comment:2 Changed 3 years ago by Chris Jerdonek

Cc: Chris Jerdonek added

comment:3 Changed 3 years ago by Aymeric Augustin

I'm the author of [7db4c81d] which added that text in CONTRIBUTING.rst.

I would be very happy if someone explained to me what process guarantees that PRs for typos won't get ignored and then lost among our hundreds of open pull requests.

comment:4 Changed 3 years ago by Marc Tamlyn

I think at present there is no particular process which *guarantees* that PRs of that nature won't get ignored potentially indefinitely, however with at least myself, Tim and Alex relatively following github notifications for Django, I know many trivial patches have been committed that way. As a note, by trivial here I mean easy typos (spelling mistakes and the like) rather than anything which needs checking out. If I can commit it without needing to do anything other than reading the diff, then I will do so directly via github. Otherwise the trac flow is useful.

In summary, there's no concrete process for this, but it does happen anyway. In any case, the documents should be specific. My personal opinion is that trac tickets for correcting simple spelling mistakes are overkill and they shouldn't be necessary.

comment:5 Changed 3 years ago by Chris Jerdonek

The current wording of CONTRIBUTING.rst implies that pull requests are guaranteed to be ignored, which isn't true either. (By the way, I think that meant to say "pull requests without tickets" are ignored.) Maybe the compromise wording can say that pull requests for trivial doc fixes are okay, but that if the pull request hasn't been acknowledged or acted upon within a certain amount of time (e.g. a week or two), then the submitter can file a ticket pointing to the pull request.

comment:6 Changed 3 years ago by Aymeric Augustin

I'd say a day or two, but otherwise, yes, this is correct. Pull request (referencing this ticket) welcome!

comment:7 Changed 3 years ago by Chris Jerdonek

I'd say a day or two, but otherwise, yes, this is correct. Pull request (referencing this ticket) welcome!

Okay, I can create one.

@mjtamlyn, because you follow the github notifications with Tim and Alex, what do you think is the right amount of time to wait for people like you three to address a trivial doc fix before filing a ticket?

comment:8 Changed 3 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: newclosed

In d430f1d98b564543d1c90d067efdf1ee6851d8d3:

Fixed #21609 -- Amended CONTRIBUTING.rst pull request guidelines.

Thanks cjerdonek for the suggestion.

Note: See TracTickets for help on using tickets.
Back to Top