13 ms·

For a one-character typo, I would probably have just reported it as an issue. An issue is sufficient to say what fix is needed, and in some ways it's easier for

by jomar 5y ago

For a one-character typo, I would probably have just reported it as an issue. An issue is sufficient to say what fix is needed, and in some ways it's easier for a maintainer to make such a fix themselves than to verify a change made by an external contributor, correct the commit message, verify their CLA status, etc. However my experience of reporting Python documentation issues has been frustrating for other reasons. I reported a lack of detail in the multiprocessing.Process.exitcode documentation in October: https://bugs.python.org/issue45554 Nearly three months later, no-one has commented on the bug report -- not even to triage it. Fair enough, it is a minor issue, people are overstretched particularly with the current world situation, and perhaps proposed fixes would be of more interest. So in late November I set about improving this documentation myself. I found the CLA process relatively straightforward, though I was unimpressed that the online signing via Adobe Sign refused to work in an incognito window. Emailing a scanned signed paper form was an effective and straightforwardly handled alternative. I filed a PR with a proposed documentation improvement in mid December: https://github.com/python/cpython/pull/30142 Apart from one drive-by comment from a non-core contributor, no-one has commented on the pull request -- not even to approve running the remaining basic workflows. Also fair enough, it has only been a couple of weeks outside the holiday period, and it is a minor issue. By now the PR is on page 4 of the cpython repo's list of open PRs, so it is difficult to imagine anyone getting back to it except by accident. The Doc-SIG mailing list appears to be mostly moribund, so doesn't appear to be a good place for a nagging message. All in all, I'm not feeling encouraged to spend time making what are intended to be useful (albeit minor so far) contributions.

k_sze 5y ago
Creating an issue and getting somebody else to check-in the code for you doesn’t give you the same level of bragging-rights feeling as actually creating a PR and getting merged though, regardless of how trivial a fix it is. I’m not saying that’s what is driving the OP, but I myself would certainly be driven by that to some extent.
Tepix 5y ago
Yep.. i came here to say the same: It's even worse to get past the red tape only to be ignored.
- matheusmoreira 5y ago
  It's even more annoying when you actually submit a patch and the maintainers end up fixing the issue themselves. All that time you spent exploring the project and studying the code to figure out how to do it yourself? Wasted. The people who already know the code and have all the context can fix whatever issue in minutes and in a better way.
  - hiptobecubic 5y ago
    It's also very discouraging (and unfair) for new comers not to get credit for that work.
  - Tepix 5y ago
    Yeah that happens quite a bit, too.
taleinat 5y ago
(I'm a Python core dev, speaking for myself.) Python is almost entirely developed and maintained by volunteers. The increasing backlog of issues and PRs is recognized as a problem. Thanks to a generous donation, the PSF has recently begun employing one "developer in residence", Łukasz Langa. He is specifically tasked with tackling this backlog, and has been doing a mighty good job so far. Still, with over 1,000 open PRs and many times more open issues, we (the Python devs) could use more helping hands. For example, anyone can confirm that bugs reproduce, review PRs, or test fixes, and those are all meaningful help (when done thoughtfully and thoroughly.) I, and most core devs, volunteer happily and ask for nothing in return. If you think the situation outlined in the parent post isn't great and begs improvement, you're welcome to help!
- jomar 5y ago
  I agree with everything you say, and alluded to much of it in the parent post. I myself also volunteer happily on a number of projects, and attempt to keep up with similar deluges on those projects. For someone like myself who is not already a core Python maintainer, how would you recommend making improvements to things like the Python documentation if not by raising pull requests?
  - taleinat 5y ago
    For a specific doc fix, a PR is indeed the way to go. If it's not a simple fix, creating an issue on the tracker may also be called for. Doing so does help and is appreciated, even if it sometimes takes a long time to be addressed by a core dev. Otherwise, one could help in ways like I mentioned previously: reading existing issues, checking if they are still relevant and commenting accordingly, reviewing PRs and patches, etc.
    - deleted 5y ago
      [deleted]
    - jomar 5y ago
      > For a specific doc fix, a PR is indeed the way to go. If it's not a simple fix, creating an issue on the tracker may also be called for. That is precisely what I did. As noted, there has been no indication (by activity on the issue or PR) that having filed these helped or is appreciated. Hence discouragement. It is one of the hard lessons of open source maintainership that, without providing feedback to contributors, there is no demonstration of the project's appreciation. Therefore new contributors will (correctly!) conclude that the project does not appreciate these efforts.
karlding 5y ago
I've submitted a few minor PRs (doc changes, typing changes, test fixes, some small features) over the last few years as a non-core developer. To be fair, some changes were reviewed promptly so the problem of reviews taking a long time doesn't necessarily reflect on Python as a whole. In my experience, typeshed changes were always reviewed promptly and Mariatta reviewed a bunch of simple doc fixes within a couple of days. Contributing to libraries that didn't have an established owner definitely took longer to get reviewed (even more so for features that only a subset of developers would use). I sent an email on the mailing list to follow up after a while and Guido ended up merging one of the changes. For another PR (to fix a broken test that had been broken for years) a core developer assigned various reviewers, who all unassigned themselves. After a year of no activity, I then followed up directly with a core developer during their office hours and we walked through the review together. Being a volunteer-run project means that they work on things during their free time, and during my discussion with one of the core developers they highlighted that since Python is volunteer-run, they can't really force anyone to do reviews—people just work on whatever they want, whenever they want. I think that's fair, but it certainly biases away from people who submit a few contributions outside of the core developer group. We also talked about the recommendations in the dev guide about reviewing code as a non-core developer, since it seemed like a sort of chicken and egg problem where people who aren't core developers won't/aren't able to review code. And even if they do, their review isn't necessarily conclusive to getting a change reviewed and approved by a core developer, who likely will just ignore their review (since there's no credibility).

by jomar 5y ago

k_sze 5y ago

Creating an issue and getting somebody else to check-in the code for you doesn’t give you the same level of bragging-rights feeling as actually creating a PR and getting merged though, regardless of how trivial a fix it is. I’m not saying that’s what is driving the OP, but I myself would certainly be driven by that to some extent.

Tepix 5y ago

Yep.. i came here to say the same: It's even worse to get past the red tape only to be ignored.

matheusmoreira 5y ago
It's even more annoying when you actually submit a patch and the maintainers end up fixing the issue themselves. All that time you spent exploring the project and studying the code to figure out how to do it yourself? Wasted. The people who already know the code and have all the context can fix whatever issue in minutes and in a better way.
- hiptobecubic 5y ago
  It's also very discouraging (and unfair) for new comers not to get credit for that work.
- Tepix 5y ago
  Yeah that happens quite a bit, too.

taleinat 5y ago

(I'm a Python core dev, speaking for myself.) Python is almost entirely developed and maintained by volunteers. The increasing backlog of issues and PRs is recognized as a problem. Thanks to a generous donation, the PSF has recently begun employing one "developer in residence", Łukasz Langa. He is specifically tasked with tackling this backlog, and has been doing a mighty good job so far. Still, with over 1,000 open PRs and many times more open issues, we (the Python devs) could use more helping hands. For example, anyone can confirm that bugs reproduce, review PRs, or test fixes, and those are all meaningful help (when done thoughtfully and thoroughly.) I, and most core devs, volunteer happily and ask for nothing in return. If you think the situation outlined in the parent post isn't great and begs improvement, you're welcome to help!

jomar 5y ago
I agree with everything you say, and alluded to much of it in the parent post. I myself also volunteer happily on a number of projects, and attempt to keep up with similar deluges on those projects. For someone like myself who is not already a core Python maintainer, how would you recommend making improvements to things like the Python documentation if not by raising pull requests?
- taleinat 5y ago
  For a specific doc fix, a PR is indeed the way to go. If it's not a simple fix, creating an issue on the tracker may also be called for. Doing so does help and is appreciated, even if it sometimes takes a long time to be addressed by a core dev. Otherwise, one could help in ways like I mentioned previously: reading existing issues, checking if they are still relevant and commenting accordingly, reviewing PRs and patches, etc.
  - deleted 5y ago
    [deleted]
  - jomar 5y ago
    > For a specific doc fix, a PR is indeed the way to go. If it's not a simple fix, creating an issue on the tracker may also be called for. That is precisely what I did. As noted, there has been no indication (by activity on the issue or PR) that having filed these helped or is appreciated. Hence discouragement. It is one of the hard lessons of open source maintainership that, without providing feedback to contributors, there is no demonstration of the project's appreciation. Therefore new contributors will (correctly!) conclude that the project does not appreciate these efforts.

karlding 5y ago

I've submitted a few minor PRs (doc changes, typing changes, test fixes, some small features) over the last few years as a non-core developer. To be fair, some changes were reviewed promptly so the problem of reviews taking a long time doesn't necessarily reflect on Python as a whole. In my experience, typeshed changes were always reviewed promptly and Mariatta reviewed a bunch of simple doc fixes within a couple of days. Contributing to libraries that didn't have an established owner definitely took longer to get reviewed (even more so for features that only a subset of developers would use). I sent an email on the mailing list to follow up after a while and Guido ended up merging one of the changes. For another PR (to fix a broken test that had been broken for years) a core developer assigned various reviewers, who all unassigned themselves. After a year of no activity, I then followed up directly with a core developer during their office hours and we walked through the review together. Being a volunteer-run project means that they work on things during their free time, and during my discussion with one of the core developers they highlighted that since Python is volunteer-run, they can't really force anyone to do reviews—people just work on whatever they want, whenever they want. I think that's fair, but it certainly biases away from people who submit a few contributions outside of the core developer group. We also talked about the recommendations in the dev guide about reviewing code as a non-core developer, since it seemed like a sort of chicken and egg problem where people who aren't core developers won't/aren't able to review code. And even if they do, their review isn't necessarily conclusive to getting a change reviewed and approved by a core developer, who likely will just ignore their review (since there's no credibility).