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. :smile: 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

[KatherineMichel]

Thank you for adding my input on here. For anyone who is not familiar with TacoFancy, it was a project that Dan Sinker began on a whim one night when he was cooking Mexican food. He began promoting the project on Twitter which resulted in pull requests ranging from professional developers to total novices. The positives that I would point out:

1). Specific guidelines for contributing 2). Inclusion 3). Learning opportunities 4). Specific feedback/directive from Dan

Though the content was unconventional, there are some lessons that can be learned here about coordinating open-source issues.

[dshack]

Seconding the suggestions for exemplar issues, as well as @ondrae's bug template. Something like that is used internally in many companies and works great.

One thing I'd add: get some momentum going by appreciating people who submit issues! Post new issues to Slack, Hipchat, or whatever, and actually make a point of reaching out, thanking people for submitting, and maybe publicly appreciating them on Twitter. Quick, positive feedback is one of the best ways to reinforce learning and action.

[mhoye]

Help Wanted or Good First Bug are great places to start.

We've got a pile of data suggesting that an ideal first bug is very narrow in scope, possibly as little as one line, and:

• The problem statement and successful outcome are unambiguous.
• The bug should link to the code to be modified.
• External requirements (OS, hardware, etc) should be explicit.
• Any relevant testing should also be identified, as well as instructions for adding any new tests, and
• The bug is not time-critical, blocking on or being blocked by anything else

Some numbers from Mozilla about reasons for patch rejection: ~25% of the time, it's for a suboptimal fix, ~23% for incomplete fixes, ~12% for overcomplete fixes, ~11% for syntax/style problems, and about 5% for test failures, so if you hold your introductory bug descriptions to those standards you can reduce your patch-rejection cycles by almost 75%.

[melodykramer]

These are questions I'm planning to answer in READMEs but also might be of use to people reading this thread:

More people would be able to use these projects — and help make them better — if every project’s documentation contained the answers to the following questions:

In plain language, what is this project and what does it do? Who made this project? Who is the audience for this project? How do I set this project up on my own machine? How do I test this project to make sure it works? Who has adapted this project and can I see screenshots or examples? Who do I contact if I need help with this project? What languages is this project in? If I wanted to help with this project, what is the best way to do that? Is the project in active development? What is the licensing on this project?

[una]

Just catching up on this thread -- thank you for the mention. i do love @melodykramer's suggestion of offering a series of questions.

We could do something similar to the a11y project checklist: http://a11yproject.com/checklist.html

Or provide a template resource starter as mentioned above. Both could be good too.

[danizen]

Most organizations already have a forum for customer service, and they will not thank us for defining a new source for issues such as https://github.com/HHS/lodestar. We use Atlassian JIRA internally. There are many add-on products that make github.com issues more usable, it would be nice to have one that is free and truly easy to deploy internally - so, guidance on what github.com issues add-ons are best, and who is using which elsewhere in government would help.

[aendra-rininsland]

If the project involves code — unit tests, unit tests, unit tests. You'll avoid unnecessary issues and automated testing makes it way easier to evaluate PRs. Requiring submitters include tests is really the only way to manage contributions once they start coming in — I took over a project with a poor test suite and mismanaged PRs had basically broken it for everyone. Make sure to use Travis too. Good inline documentation will also help.

Beyond that I don't have much that hasn't been said. Secondary support channels are really crucial to avoiding an endless issue queue full of general use questions — with C3, we use both Google Groups and Gitter. Gitter is really good for building a generalised support community and Google Groups are good for asynchronous discussions.

[drapostolos]

There is a really great book about this topic (in general), called "Producing Open Source Software - How to Run a Successful Free Software Project" (http://producingoss.com/)

A bit old, but still very good.

[tmcw]

These are some great ideas! Some minor points:

• The ideal project description is no longer than a few sentences, regardless of how much complexity the project encompasses: like any piece of writing, the thesis should be prominent and well-written. If there's more to say, break it out into a separate section so the summary is still digestible.
• The way that external contributors contribute to your project should be the same way you do. Do not maintain a separate copy, don't have long off-list discussions, don't work in the master branch but expect others to send pull requests. Not only does working the same provide a better sense of community, it makes it clear how work gets done and leaves lots of public examples of how tickets are filed and issues are discussed.