DOC Set expectations for contributors proposing significant work #32660
Conversation
A maintainer is an important ingredient in moving work forward. Make people aware of this.
There was a problem hiding this comment.
In essence a good idea, thanks, @betatim!
The message needs a bit more work, I think.
I think the focus on people hierarchy (you can be lucky/reputated enough to catch a maintainer's attention) instead of on structure that would also involve the contributor reads like we've given up trying to deliver a timely response. We could at least express our regret that deciding on a new feature takes more time than scikit-learn maintainers have at their hands. I bet many people are not aware of that.
For me it is still the first time that I have heard of the word "champion" in this context and I think we could also trigger this message with "Needs decision".
|
I read the review comments and decided to rewrite the text quite a bit. Trying to take into account the comments in the process |
glemaitre
left a comment
There was a problem hiding this comment.
I like the phrasing and the fact to trigger it with the label could be nice I think.
StefanieSenger
left a comment
There was a problem hiding this comment.
Thanks, @betatim! I like the more concise comment that starts on "thanks". I have only got some suggestions, but would be happy to have it as is, too.
| Please do not create a Pull Request before a decision has been | ||
| made regarding the proposed work. Making this decision can | ||
| often take a significant amount of time and effort. |
There was a problem hiding this comment.
Proposing an alternative with a more obvious recommendation to act for the author and to better express what "significant amount of time" means. It is just a suggestion, since I am happy with the current text too:
| often take a significant amount of time and effort. | |
| Deciding on new features or substantial changes is a lengthy | |
| process and requires a significant amount of discussion and | |
| coordination. It frequently happens that no maintainer is available | |
| to take on this task right now. As a result, the full process often | |
| starts delayed or not at all and spans months to years. | |
| For now, please hold off on additional implementation work or | |
| creating a Pull Request until a decision has been reached. |
| issues: write | ||
|
|
||
| on: | ||
| issues: |
There was a problem hiding this comment.
It is triggered on issues: Does that mean that if we add "Needs Decision" to a PR, it won't post the comment then?
There was a problem hiding this comment.
Yes. I don't know if we want this for PRs. Theoretically/Ideally there should be no PRs that need a decision, because you only create a PR once there is a decision. But yeah ...
There was a problem hiding this comment.
I think its fine as is. Posting this comment on an issue that "Needs Decision" has more effect than posting this on a PR that "Needs Decision".
I think we would sometimes use "Needs Decision" if we change our opinion in the middle of reviewing a PR and then need to discus or decide about it again (in which case the context would explain to the author of the PR that it is a lengthy process and please better wait until it's decided).
Only the case when contributors open a unsolicited larger PR without having discussed that change in an issue before is not covered here. We can in this case still copy this comment from somewhere else.
|
@betatim, did you test this somewhere? |
Co-authored-by: Stefanie Senger <[email protected]>
|
I've not tested this on my fork. |
| Deciding on new features or substantial changes is a lengthy | ||
| process. It frequently happens that no maintainer is available |
There was a problem hiding this comment.
Do you think it is worth adding background information on how a "new feature is like giving someone a puppy" - often people think a new feature only requires the work of adding a new feature (why not 'just' add this?) but cannot see the longer term maintenance required.
There was a problem hiding this comment.
I think that is too much level of detail. The longer the text, the lower the chances of people reading it. The way I think about these things is along the lines of checklists (as used in aviation). They aim to remind pilots of the things that need to be done, but if you don't know how to do the thing they are useless.
For me this is a reminder to everyone, including maintainers, not a moment to teach people. If you want to go fly you probably know what "Cockpit prep" means, and if not you should ask. But I assume that question means you won't fly today and instead go away to a classroom to learn about it.
|
What do you all think about merging this, starting to use it and then fine tuning based on what we learn? |
lucyleeow
left a comment
There was a problem hiding this comment.
I'm okay with merging it. I think it would be nice to add that we may 'never' make a decision (or takes so long it is not longer relevant), to really set expectations.
To make it sound 'nice' we could say something like; "for some issues, consensus is never reached".
A maintainer who has the time and interest is an important ingredient in moving work forward. The goal of this PR is to make it easier to make people aware of this.
The idea is to provide a label ("Needs Decision") that can be applied to an issue that will trigger a comment to be added that explains that, based on past experience, work that has no maintainer to champion it is unlikely to be merged. The goal is to raise awareness about this fact to help set expectations. The goal is not to use this to discourage people or suggest that an issue is not interesting/important/useful. The goal is to explain why sometimes even very good ideas don't happen for a long time.
Why is this a label + bot? We could each have a message similar to this in our "saved messages" and post it. The downside to that is that everyone would have slightly different messages and that by posting in an issue you are marked as participating in it. This means you will receive notifications with a higher priority, it might also create the impression that you personally want to/don't want to participate in the discussion (instead of just making people aware of the fact).
A risk with this message is that contributors will start @-mentioning individual maintainers to attract their attention. If this starts happening we can address it then.
We discussed this topic at the Scientific Python Summit (@lesteve @StefanieSenger @glemaitre). What do others think?
xref scientific-python/summit-2025-nov#6