#35894: Move away from the term "patch" to refer to a contribution/pull request
in
the contributor documentation
-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Baptiste
Type: | Mispelon
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Baptiste Mispelon):
Thanks everyone for the feedback, I'll try to address it point by point
1) Not breaking existing URLs
This is a very good point, but I think we should address that via setting
up 301 redirects in the server configuration (this is something I can do
as a member of the ops team)
I'll also note that there is some precedent for breaking docs links (found
via `git log --diff-filter=RD --stat -- docs/`):
d8b6a76bc745b21c6cf2b29c220a91bcae7fd3d7,
8eae094638acf802c8047b341d126d94bc9b45a3, or
3d14cbc86781ea1051af7f0c421bee3ecf2f9842
2) Not breaking URL fragments / heading names
I'm not opposed to re-adding some directives like `.. _patch-review-
checklist` to try and preserve deep links people might have used, but I
think it should be part of a documented policy. Why is this heading on
this page important that it requires preserving? Should that apply to all
references throughout the documentation? If not, what's the cutoff, how do
we measure it?
I don't think it's realistic to expect headings not to ever change names,
and without a policy in place (ideally enforced by some kind of automated
tool) those "backwards-compatibilty" references are at risk of being
removed by accident.
3) Githubisms
I would argue that the term "pull request" is general enough as to not be
a "githubism" (it is used on bitbucket for example). In any case, this
word reflects the reality of our contributing process today and for the
foreseeable future, unlike the word "patch" which one could also call an
"SVNism" .
4) Patch is a generic term
I think that one might be a matter of opinion (and mine is that it's not)
which would be hard to quantify objectively. My belief is that the
majority of our new contributors do not know what a "patch" is, but they
know what a "pull reqest" is.
I'll also point out that the Python devguide recently made changes in a
similar direction:
https://github.com/python/devguide/commit/0ad84cdd913dfd58df1fe4862eb7bf06cc8f4882
Also also, our documentation currently uses the word "patch" for several
different meanings:
1) As a synonym for "pull request" essentially
2) To point to a specific commit in the context of a security release
3) A "patch" release
4) The HTTP method
Replacing one of these (1) would be an improvement in my opinion.
--
Ticket URL: <https://code.djangoproject.com/ticket/35894#comment:7>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019306a6b2b7-b1df6db9-660b-4d65-94b4-af9d04a17c9b-000000%40eu-central-1.amazonses.com.
