#21609 closed Bug (fixed)

CONTRIBUTING.rst contradicts the contributing guidelines

Reported by: cjerdonek Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: cjerdonek 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 22 months ago by bmispelon

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 22 months ago by cjerdonek

  • Cc cjerdonek added

comment:3 Changed 22 months ago by aaugustin

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 22 months ago by mjtamlyn

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 22 months ago by cjerdonek

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 22 months ago by aaugustin

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

comment:7 Changed 22 months ago by cjerdonek

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 22 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

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