• Introducing to Contributor Guidelines
• Assignment: Write Contributor Guidelines

Introducing to Contributor Guidelines

Now that you’ve set out guidelines for behaviors within the community, and asked contributors to approach participation with a specific mindset, we’ll lay out the actual process by which can participate– the stuff they’ll do. Contributor guidelines, which we’ll write in a file we’ll call title CONTRIBUTING, are the nuts and bolts instructions on how to contribute to your project. (Along with the README file, the idea of a CONTRIBUTING file is borrowed from the software engineering world, where it is a conventing to capitalize the filenames of very important files.)

In the next section, getting started with GitHub, you’ll get your project files online in a place where people can find them and contribute to your project. This CONTRIBUTING file (along with the project README you create) will be one of the first things that potential contributors to your project see. You can write this file with whatever text editor you prefer, or with good old pen and paper– in the next module you’ll learn how to format it for life on the web, with links to other key files.

There are three audiences for this file:

• Your potential contributors, people who want to know what they can help out with, the process and conventions they’ll need to follow in making contributions, and they way they are expected in interact with other members of the community

• Project consumers, those who want to build off the work you’ve done, remix and reuse it to create their own project. This file should give them a sense of how best to do that, and what’s allowed.

• You, the project lead, who creates and maintain this file. You’ll want to update this file as the project evolves. The process of writing this file will also help prep you for good interactions with your community.

If possible, write a draft of the CONTRIBUTING file with members of your community, if you have already engaged with them. This will help them feel a shared sense of responsibility and to create the best possible guide for encouraging new contributors.

Assignment: Write Contributor Guidelines

1. Reflect / Plan Start by reflecting on what to include, and what kinds of contributions to invite. Browse these examples of CONTRIBUTING files from diverse projects.

   • Small project, some field, etc

   • Medium size project, field, etc.

   • Big software project example of the Atom.io CONTRIBUTING.md file.

   The following elements should appear in your CONTRIBUTING file. If you don’t know the details right now, it’s OK to write “more details coming soon!” for that section. Remember, you’ll often return to this document to update it as your project evolves. But if you’ve completed the previous modules, you should have the first 4 items on this list already! Take a few notes as you read through the list, plan and reflect. You’ll write up your CONTRIBUTING file in the next step.

   1. Restate your project vision, in one sentence. Redundancy is your friend!

   2. Welcome contributors to the project: Let them know that you are eager for contributions and happy that they’ve come. This is a great place to introduce yourself so people see that there’s a name and face that goes with this project.

   3. Point people to your Code of Conduct for the project, and require users to read it before they go any further.

   4. List Important Resources where contributors can see what kind of work is currently happening on the project.
      • Readme
      • Roadmap

   5. List Communication Channels: if you are using forums, chat clients, email lists or other ways of communicating about the project, list those here and provide instructions on how to join. (more on this in section x, don’t worry if you don’t have this all figured out yet)

   6. Tell readers how to submit changes: This is the process for adding your work or changes to the repository or collection of ongoing work (Leave this blank for now– we’ll cover how to manage contributions on the web with an open workflow in the next module.)

   7. Describe Good First bugs for Contributors: Guidelines for the types of “bugs” or useful, helpful tasks new contributors should start with as they’re first coming on to a project. A bug often refers to a problem that needs to be fixed. These should be small, fairly easy but meaningful tasks that get a new contributor started and provide an early, encouraging success. For a very new project, a good first bug might be to ask contributors to comment on your README file– does it make sense, do they understand the project? Is all the information they need there? Are there any typos?

   8. Tell readers how to report a bug: Ask your contributors to stay on the lookout for can any potential issue that might cause problems for the project. These could be problems in code (if you’re creating software), content omissions or copy errors (if you’re creating a learning resource), or any issues with the functionality or design of your project. Basically, by asking users to report bugs, you’re asking for feedback on work that’s been done. Most projects invite all contributors to reporttell the project lead about bugs, so “debugging” or fixing problems happens quickly and with the input of the community. Take a look at Atom’s example for how to teach people to report bugs to your project. (Again, you may want to add to this section after you get comfortable with GitHub, and get everything online)

   9. Tell users about your recognition model - Remember, you need to acknowledge value of the time and work your volunteers give your project. Here, provide a pre-emptive “thank you” for interest contributing. List any recognition contributors might receive for participating in your project. You can also outline how contributors can “level up” to become project maintainers (a certain number of bugs resolved, a certain number of changes or contributions successfully submitted to the project). You can leave this blank for now, and fill it in later.

   10. Let users know where to go for help - provide clear contact info, and outline the process for getting in touch, for anyone with questions.

   Here are some elements that are optional for your CONTRIBUTING.MD file. See if any of these make sense for your project.

   1. Templates: You might want to link to templates, which contributors can copy and add context to; templates help guide contributors on what information to include, and how.

   2. Info on how to request an “enhancement” - enhancements are features that contributors suggest for a project, but aren’t necessarily bugs/problems with the existing work; there is a “label” for enhancements in Github’s Issues so contributors can tag issues as “enhancement” – not the same priority as a bug or current task, but important as the community helps guide the project’s design and evolution. See Atom’s example section.

   3. Style Guide / Coding conventions - If your project is a coding project, it’s important to designate how See Atom’s example.

   4. Who is involved? - Open Government’s CONTRIBUTING.md . You might list the core contributors and their preferred methods of contact here, or link to a humans.txt. Here is an example of a humans.txt file.

2. Write up your a CONTRIBUTING file. Now that you’ve reviewed what goes into the CONTRIBUTING file and given some thought to how you want newcomers to engage with your own project, take your notes and write up your own CONTRIBUTING file. In the next section, we’ll get your project (and this file) online using the GitHub platform for collaboration.

Help us improve content and suggest changes to this page.