How To Make a Delicious Contributing Guide

Introduction

Picture this. You’re looking at the recipe for a pizza and the directions are missing specific measurements, and key ingredients, leaving your kitchen a mess and you starved, and confused.

This is pretty much the same experience that occurs when people struggle with making an effective contribution to a project. No clear directions equals a digital disaster. This is where a well-crafted contributing guide comes in. This guide is typically found as a separate file and hyperlinked to the README file in a project’s repository.
In this blog post, you’ll learn the ingredients of a well-made contributing guide and its benefits.

Ingredient 1: Getting Started Section

You know how in a pizza recipe, there is a section that lists the ingredients? Well, the Getting Started section serves a similar purpose. This part of a contributing guide is where the owner introduces their project, which helps you learn more about it. This section tends to list the languages that the project is built with and provides links to additional resources to learn how to use Git and GitHub. It also adds links to the project’s Code of Conduct file, describes ways you can interact with other contributors and maintainers, and briefly mentions different examples of contributions you can make to the project. An example of a strong Getting Started section would be the one from Codecademy's Docs repository.

As shown in the picture above, Codecademy briefly describes their project and provides steps on how to contribute. They also provide a FAQ section, a great resource for people who have never contributed to an open source project. Now, the Getting Started section is only one of the main ingredients of a contributing guide. Let’s check out the others! :)

Ingredient 2: Commit Guidelines

This part of the contributing guide is where you describe how you want your commits constructed. You can add things like examples of commit messages so contributors have an idea of how to formulate these messages. A good example of a project that provides guidelines for commit messages would be LinksHub.

In the screenshot above, they provide examples of effective and ineffective commit messages, which helps contributors gain a better understanding of how to write them. Commits are like the crust of a pizza. They both help keep the food (or in this case, your project’s codebase) strong.
Speaking of a strong foundation, there’s another section of a Contributing Guide where creating one is important.

Ingredient 3: Setting up the Codebase’s Environment

In this part of the contributing guide, you learn about the tools and software needed to submit your contributions. They're like your sous-chefs helping you to chop the veggies and make the dough and sauce. You'll also find links from the project's README, guiding you as you set up your IDE workspace to create contributions. Think of it as picking the ideal oven and setting the perfect oven to make a pizza that will make your tastebuds groove. A great example of this would be freeCodecamp’s Set Up chapter.

In the above image, freeCodeCamp recommends which IDE best suits your contributing needs. This project also provides you with a step-by-step guide on how to fork its repository. Now before you go get some pizza, there’s just one more ingredient you need to make a well-baked contributing guide.

Ingredient 4: Issue and Pull Request Guidelines

This section of a contributing guide presents instructions on how maintainers accept and approve pull requests and issues are described. These guidelines ensure that your contributions will be reviewed and effectively merged into the project’s codebase. Now, here are a few things you should keep in mind when reading this information. In the subsection that provides issue guidelines, you often see:

• A list of what issue form to use when proposing a specific contribution
• Tips on how to effectively fill out the form
• Labels to use to categorize the issue.

Pull Request guidelines, on the other hand, tend to have the following:

• Step-by-step instructions on how to create your branch
• Instructions on how to write the title of your pull request.
• A form with commented steps that show you how to fill out each section. The Odin Project exemplifies these guidelines perfectly.

As shown in the image above, this project provides instructions on how issues will be assigned and what to avoid when making a pull request. It’s similar to the side notes that you see on a recipe.

All in all, the contributing guide is like the recipe instructions for your open source project. It brings balance to your project and provides tips that lead to delicious and well-baked contributions. Now login to your OpenSauced account (if you don’t have an account, check out the Discover Open Source with OpenSauced section of our Intro to Open Source course to learn how to create one) and start cooking! Who knows, your first pizza-I mean contribution, could be editing this project’s contributing guide! 😉

Credits

Photo of recipe by James Lee on Unisplash