streamline contribution guidance

[katrinleinweber]

Hello!

From my initial stumbling (1k thanks to @stkent for the hints 🙂 ) and this, I gathered that PR templates might be useful for this repo as well.

I suggest creating a .github folder (and would be willing to do it) for

1. CONTRIBUTING.md (just moving it), and
2. a PULL_REQUEST_TEMPLATE.md(workflow details extracted from README.md and CONTRIBUTING.md, for example in the form of a task list).

IMHO, this could bring guidance info to the... Actionable point and time of contact, so to speak. Particularly new contributors may feel that the two existing files are rather a lot to read (me: guilty as charged 😅 ). Seasoned contributors could of course skip over or remove the items, but would also be reminded about the current UX for newbies.

What do you think?

PS: Albeit also touching a general topic, this topic seems more "actionable" here than "other" ;-) PLMK if I should move this issue there.

[kytrinyx]

@katrinleinweber This sounds good.

My recommendation for the pull request template would be to make it a task list where each item in the list links out to a relevant section of the contributing guide.

That would make it less overwhelming (not a wall of text in the pull request that you open up), easy to skip past if you don't need to read (just check off the items), while still making the help text available and relevant.

[Insti]

I really think this is a bad idea and the cure is worse than the disease.

• It pollutes pull requests with information that does not need to be there.
• Is anyone who has not read the contributing guide going to read them because there was a checkbox in a pull request template?
• The checkboxes drown out pull requests that really need to use todo lists.
• It makes contributing a Pull request HARDER because there is now a lot more stuff you need to go through by either jumping through its hoops or deleting it.

[Insti]

Particularly for new contributors, e may feel that the two existing files are rather a lot to read (me: guilty as charged 😅 ).

Creating a section in the documentation that you WOULD read seems like a better solution.
(This is almost what you've done in #853 ❤️ and I would be in favor of that WITHOUT making it a pull request template.)

[katrinleinweber]

Hi @Insti! I think my reply in #853 addresses your above points as well.

To advance the general discussion here, I would argue: In the long term, all PR- or issue-specific instructions should be succinctly put into a template, with link to more verbose explanation where necessary. IMHO, the trade-off between deleting what is not necessary on a case-by-case basis (very small effort often) and using a platform feature to provide actionable advice in the moment they are necessary (increases contribution quality) is worth making.

[kytrinyx]

I'm with @katrinleinweber on this one.

1. The templates show people the right information at the right time.
2. They act like checklists
3. They should be succint
4. Verbose information should live in the contributing docs, and be linked to