Opensource.guide: Create a guide on "healthy interactions on a project"

[hzoo]

discuss possible topics and collect stories, quotes, and other references?

@bkeepers asked me to create an issue on this after I brought it up in the maintainers repo.

for example: how to create issues (so meta)!

My thoughts on this was that I totally remember feeling like I didn't know how to even start creating an issue when I first started (similarly for creating your first PR, which should be a topic too actually).

I recently got asked about this by a new contributor as well as my coworker (@bossjones). He was for looking for some tips on how to create an issue on an OSS project (without coming across in the wrong way, since it's an edge case).

• general etiquette online: http://www.albion.com/netiquette/
• how to create a good issue (for the maintainer)
  
  
  
  • following the issue template, if there is one
  
  
  • neutral tone, but important to note if it's a regression from the latest release rather than just a bug. If you come across as entitled (threaten to stop using the project, complain about spending lots of work time figuring this out before making an issue or asking) don't expect to get the help you want?
  
  
  • provide the necessary/relevant information for a maintainer to reproduce the issue (goes both ways if a maintainer can provide tooling such that you don't have to create a whole git repo) - in Babel many times you can just the online repl to reproduce.
  
  

I was initially thinking about this from the issue creators point of view, but of course we should also talk about maintainers and how they can respond to users.

There's a lot to talk about here so looking forward to everyone sharing 🙂!

[bkeepers]

CCing a few people who may have some good resources or insights: @gr2m @mikeal @lee-dohm @MikeMcQuaid

I was initially thinking about this from the issue creators point of view, but of course we should also talk about maintainers and how they can respond to users.

I think the issue creator side is really important and currently lacking. We could later update Maintainer best practices or add another guide for the maintainer perspective to accompany the issue creator guide.

[hzoo]

I guess there's also how to create beginner-friendly issues for new contributors (I learned from @gr2m)

It's way more work than just creating a new issue and waiting, but has been working very well for straightforward changes (usually refactoring/infrastructure)

An example I got from "Welcome to Open Source" https://github.com/babel/babel.github.io/issues/754 - has a cool header, explaining the issue in detail + instructions + checkboxes and more

I took this sort of idea for all the "beginner-friendly" issues in Babel 7

[gr2m]

As a maintainer, creating issues which are clearly "up-for-grabs" and well documented are working great. We have a dedicated repo full of these: https://github.com/hoodiehq/camp. They do take more work, but they set expectation (It’s okay for you to just claim this, no need to ask for permission), they set a tone, they clearly communicate how much you care about others, they help onboard new contributors as well as new maintainers (the step-by-step instructions are great for PR reviews).

I haven fully read the he Open Source guide yet, but in terms of healthy interactions, I would try to make people aware that there a volunteers on the other side, ask them to be patient and friendly, ask them to use gender-neutral language, ask them to provide as much context as they can if it is a bug report, ask them to not put too much work (e.g. sending a PR first) before discussing an idea first

[kytrinyx]

similarly for creating your first PR, which should be a topic too actually

💯

I think this would make sense as a stand-alone guide. I've opened #304

[MikeMcQuaid]

provide the necessary/relevant information for a maintainer to reproduce the issue (goes both ways if a maintainer can provide tooling such that you don't have to create a whole git repo) - in Babel many times you can just the online repl to reproduce.

My TextExpander template for this I use regularly is:

To help us debug this issue can you explain:

• What you were trying to do (and why)
• What happened
• What you expected to happen
• Step-by-step reproduction instructions (with as minimal input data as possible)

[nayafia]

general etiquette online: http://www.albion.com/netiquette/

For this section we have "Communicating Effectively"

how to create a good issue (for the maintainer)

This part should go into "Opening an Issue", feel free to expand on that section.

I would loooove to see something for the issue creator's side. As @bkeepers suggested, that could become a section in the "Best Practices for Maintainers" guide. Feel free to tackle it!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.