Augment Getting Help docs.

[benjyw]

Lay out expectations for how to ask for help.

[huonw]

I like this in principle, thanks for taking it on

[huonw]

I strongly appreciate encouraging people to provide the right info straight up, but I'm a little concerned about phrasing some of this stuff too strongly in terms of "you must do all these things [or else you'll be ignored for process reasons]" which seems... scary, especially for someone new to open source.

I'd personally prefer to phrase it in terms of what's in it for the asker, i.e. focus on "help us help you" / "you'll fix your problem quicker if you make it easy for us to help".

For instance:

Suggested change

	You are far more likely to get a positive response if you demonstrate that you've put in the basic legwork first.
	You are far more likely to get a positive response if you make it easy for people to help you.

But I think potentially this whole section could be reframed slightly to be cast in that light, especially the list above.

What do you think?

[sureshjoshi]

Are there any projects that do this kind of language well (friendly, while direct and helpful?).

I'm always a fan of how Svelte phrases things, for example.

[huonw]

I'm always a fan of how Svelte phrases things, for example.

Ah yeah, I like it too.

Somewhat tangential but that text there makes me wonder if we could also update our bug report template to be more specific about what's expected.

Are there any projects that do this kind of language well (friendly, while direct and helpful?).

Good question! I don't know of any particularly good examples of the top of my head.

I know Rust (used to) put a lot of effort into helping new-comers, and this is their current "generic bug" issue template:

<!--
Thank you for filing a bug report! 🐛 Please provide a short summary of the bug,
along with any information you feel relevant to replicating the bug.
-->

I tried this code:

```rust
<code>
```

I expected to see this happen: *explanation*

Instead, this happened: *explanation*

### Meta
<!--
If you're using the stable version of the compiler, you should also check if the
bug also exists in the beta or nightly versions.
-->

`rustc --version --verbose`:
```
<version>
```

<!--
Include a backtrace in the code block by setting `RUST_BACKTRACE=1` in your
environment. E.g. `RUST_BACKTRACE=1 cargo build`.
-->
<details><summary>Backtrace</summary>
<p>

```
<backtrace>
```

</p>
</details>

[benjyw]

I'll just take this bit out.

[huonw]

Minor thing, but maybe this should be a numbered list:

Suggested change

	- First, do your best to solve the issue on your own. The Pants [source code](https://github.com/pantsbuild/pants), [issue tracker](https://github.com/pantsbuild/pants/issues), and [documentation](https://pantsbuild.org)
	1. First, do your best to solve the issue on your own. The Pants [source code](https://github.com/pantsbuild/pants), [issue tracker](https://github.com/pantsbuild/pants/issues), and [documentation](https://pantsbuild.org)

[huonw]

We could potentially also call out "provide support to others" as a useful activity, in addition to fixing issues.

[huonw]

In addition to the framing general concern, sometimes it's quite hard to create a reproducer, e.g. inconsistent things like pantsbuild/pants#19748, or performance issues at scale. Obviously a reproducer is helpful and really valuable, but it'd be unfortunate to completely discourage people from filing issues about those sort of things, at least as a place to have the community start "taking notes"/collaborating a reproducer.

I don't think we're at the scale of incoming issues where it's a major burden to encourage/remind users for a reproducer.

So suggestion for two actions:

• the phrasing of this to be something along the lines "provide a reproducer, or if not possible, all the information you can, e.g. pants.toml and relevant BUILD files"
• we (i.e. Pants maintainers) could start labelling such issues "requires reproducer" or something and then semi-regularly do a (manual) clean-up of such issues? E.g. if there's a bunch of unreproduced issues sitting around for a while, go through and close them.

Thoughts?

[sureshjoshi]

the phrasing of this to be something along the lines "provide a reproducer, or if not possible, all the information you can, e.g. pants.toml and relevant BUILD files"

What about some location (ticket, repo, whatever) where we have a set of common things we ask for (maybe something we could automate, anonymized into Pants CLI) - so, pants.toml, BUILD files, logs, neofetch data, etc... There would end up being a ton of superfluous data 🤷🏽

we (i.e. Pants maintainers) could start labelling such issues "requires reproducer" or something and then semi-regularly do a (manual) clean-up of such issues? E.g. if there's a bunch of unreproduced issues sitting around for a while, go through and close them.

OfficeJ auto-closes in 4 days, which is infuriating:

After an initial human triage of staleness, I'd be more open to a longer-running auto-close bot at like 3 months or something? I was looking at the issue backlog and seeing tickets that haven't been updated from mid-2018

[huonw]

What about some location (ticket, repo, whatever) where we have a set of common things we ask for (maybe something we could automate, anonymized into Pants CLI) - so, pants.toml, BUILD files, logs, neofetch data, etc... There would end up being a ton of superfluous data 🤷🏽

Putting it in a specific list of information to these docs might be a start?

OfficeJ auto-closes in 4 days, which is infuriating:

After an initial human triage of staleness, I'd be more open to a longer-running auto-close bot at like 3 months or something? I was looking at the issue backlog and seeing tickets that haven't been updated from mid-2018

Yeah, fully agreed: auto-closers are user-hostile. I'm thinking the label could be used for a human to go and find issues easily, and then close them out manually (or potentially not close them, e.g. if someone did provide a reproducer but it wasn't noticed). Pants doesn't receive that many issues 😄

[benjyw]

I don't think we're at the scale of incoming issues where it's a major burden to encourage/remind users for a reproducer.

Not sure about that. It is a frequent nuisance when people post questions lacking important information, or dump snippets directly into slack.

[benjyw]

PTAL