As a person who is setting up their first open-source repo, I'd like to know if there's any actions I should take to make my repo more friendly for people to submit issues to.

[jenniferthibault]

I've read the sections on structuring my own issues and creating README's, but is there anything that I can and should do to help structure how people submit issues before the repo is live?

For issue submitters, I'd like to make that experience a positive and easy one.
For my project team, I'd like to make sure that we receive issues and feedback that we can make actionable.

[benlk]

Assuming it's a GitHub repo, a CONTRIBUTING or CONTRIBUTING.md file placed in the project root will be linked to on the New Issue and New Pull Request screens. Having a checklist of things to include in an issue or PR is probably a good idea, as well as a link to your code of conduct and other contact methods. Here's INN's PR guidelines and the Texas Tribune's PR guidelines, as examples.

Apart from documentation, fast triage is probably a good thing, especially when coupled with feedback for the submitter from the triage person.

[patrickmj]

What comes in will be random an unpredictable. Readable code, and ability to submit small pull requests on that (well documented) code, will be the first start. Then random, unpredictable things will happen.

The other end will be more important. Responding to comments or PRs, especially if the response to a PR explains why it is or is not accepted, will go miles.

UPDATE: in short, what @benlk said.

[jenniferthibault]

This is a great, friendly starter! Thanks @benlk & @patrickmj .
@melodykramer what do you think about working some of this into a section about best practices for managing feedback, or managing an open source repo? (Framing, wording, I don't know) I could see it as a nice next step from the other sections, which are about setting things up: this gets to how to keep it going.

[melodykramer]

@jenniferthibault I think that's a great idea. Adding to my to-do list for the week. Thanks for asking the question. (And would love to see more responses.)

[mbland]

This is a great, friendly starter! Thanks @benlk & @patrickmj .
@melodykramer what do you think about working some of this into a section about best practices for managing feedback, or managing an open source repo? (Framing, wording, I don't know) I could see it as a nice next step from the other sections, which are about setting things up: this gets to how to keep it going.

All the more important for us now, given all the attention our Guides are getting. 😄 So often we publish our work as open source, or use open source products, but the real power is in empowering others outside the team to participate in the development process.

[benbalter]

Ten suggestions, specifically for government-maintained open source projects:

1. External engagement
2. Internal collaboration

[mebates]

Good tip from @una and @GarthDB at Oscon: add design and writing sections to your contributing.md so you can get input from those disciplines as well. How can they help? What are the guidelines for feedback?

[humancompanion]

I didn't see this mentioned in the resources provided above, and perhaps it isn't possible to be transparent about your project plan but, I tend to do two things to start with:

1. Establish labels and milestones. That should indicate to potential issue creators that you are organized and ready to receive issues. Milestones in particular provide some insight into the project plan and what stage the is project in.
2. File some issues. Lead by example and file some yourself. Ideally, these issues will be exemplary. Being transparent about what you plan to build and how will help folks understand where the project is going, what issues already exist, and where they can jump in and contribute.

[maya]

@jenniferthibault Add a custom label: help wanted so people feel open and invited to lending a hand.

Then it can also get fed in to Code for America's Civic Tech Issue Finder, cc @ondrae who built it.

[patrickmj]

Assuming that this happens on github, it might also be helpful for developers to know if there's a branching/merging model, like git-flow, that you follow, and any variations that the dev team has adopted.

Similarly, and echoing @humancompanion 's suggestion of 'exemplary issues', an explicit example issue structure that you have adopted would be great. This thread already looks like a recognizable structure from Agile of "As a X ... I'd like Y". But I've seen (and done) that structure with variations. For example, one team I worked with tried out using a "Works when...." section that describes from the issue-creator perspective what, precisely, is the Y that they'd like.

Not sure if the team wants to go that far, but the idea of an exemplar issue template that works for you and your team might help guide outsiders. (Might also be useful internally?)

[GarthDB]

Hey @mebates thanks for the mention.

On the Open Design Foundation repo, we have made sure to add a CONTRIBUTING.md file with recommendations for contributing code, design, and content. This file shows up when filing an issue or submitting a pull request.

If there is anything I can do to help, let me know.

[webmaven]

Having an exemplar issue (or several) linked from the CONTRIBUTING file will help a lot (especially if you can eventually replace them with ones from actual external contributors) . Unfortunately, Github does not currently support using templates for issue creation, which I think was one of the features that allowed projects on Google Code Project Hosting to onboard new contributors well (except when project maintainers didn't actually follow up, of course), so, follow-through with prompt responses to issues new or ongoing (triage, including pointing to the exemplars, labeling, friendly and constructive feedback, etc.) and maintaining the contributor's engagement all the way through acceptance of a PR (perhaps from someone else) becomes key.

If you have to actually reject a contribution (a feature request or a pull request, for example) for being out of scope, do it in as nice and clear a way as you can so as to encourage the contributor to try again and not have them give up (remember, this may be their first interaction with an open project ever).

Finish up by documenting accepted external contributions in visible ways (release notes linking to issues and PRs, significant contributions acknowledged in the CHANGES file, offering external contributors a more official role (expanding the triage team is an obvious first step) etc.

[ungoldman]

Hi! This is a great idea. I wrote a short list of things that make for a good open source project a while back, I hope this is helpful: https://gist.github.com/ngoldman/88ab15a3eeadcb06103b

As people above have said, contribution guidelines are a great way to get people introduced to participating in a project and the expected conventions when submitting issues and pull requests. I took some queues from https://github.com/jden/CONTRIBUTING.md and http://openopensource.org to make these guidelines: https://github.com/ngoldman/contributing. They are not applicable to all projects but hopefully can provide a good reference.

+1 to @maya's comment. The help wanted tag in issues is also a good way to invite participation and collaboration.

I often add a Contributing section to the README.md. You can link directly to a CONTRIBUTING.md file straight from README.md and github will make the link work for you, like so:

## Contributing

Contributions welcome! Please read the [contributing guidelines](CONTRIBUTING.md) before getting started.

[ondrae]

+1 @webmaven to linking to example issues

Recommending that the contributors include these sections to their issue can help them gather their thoughts:

Description

How To Reproduce (for bugs)

Screenshot

Files

To Do (for enhancements)

• Step one
• Step two etc

[melodykramer]

Katherine Michael also points us to Dan Sinker's Tacofancy: https://github.com/sinker/tacofancy