{"id":294887,"date":"2019-09-09T07:10:14","date_gmt":"2019-09-09T14:10:14","guid":{"rendered":"https:\/\/css-tricks.com\/?p=294887"},"modified":"2019-09-09T07:10:15","modified_gmt":"2019-09-09T14:10:15","slug":"how-to-contribute-to-an-open-source-project","status":"publish","type":"post","link":"https:\/\/css-tricks.com\/how-to-contribute-to-an-open-source-project\/","title":{"rendered":"How to Contribute to an Open Source Project"},"content":{"rendered":"<p class=\"explanation\">The following is going to get slightly opinionated and aims to guide someone on their journey into open source. As a prerequisite, you should have basic familiarity with the command line and Git. If you know the concepts and want to dive right into the step by step how-to guide, <a href=\"https:\/\/css-tricks.com\/?p=294887&#038;preview=true#article-header-id-8\">check out this part of the article<\/a>.<\/p>\n<p>Truly, there is no one way to contribute to an open source project, and to be involved often means more than code slinging. In this article, though, we\u2019re going to focus on the nitty-gritty of contributing a pull request (<abbr>PR<\/abbr>) to someone else\u2019s project on GitHub. <\/p>\n<p><!--more--><\/p>\n<h3>Let&#8217;s set the stage&#8230;<\/h3>\n<p>You come across someone&#8217;s project on Github and you love it! You may even decide to use it in your own project. But there\u2019s one small thing you notice&#8230; it could be a bug. It could be an enhancement to what\u2019s already there. Maybe you looked through the code and found a nice, optimized way of writing things that\u2019s a little more legible, even as small as an extra indentation in the code.<\/p>\n<p>Here are some initial suggestions and instructions on where to go from here.<\/p>\n<h3>Look for a <code>CONTRIBUTING.md<\/code> document or Contributing Guide in the documentation<\/h3>\n<p>Many open source projects know that other people might want to contribute. If they find themselves answering the same question again and again, this document intends to make it easier to get everyone on the same page.<\/p>\n<p>Some things you might find in a Contributing guide:<\/p>\n<ul>\n<li>Style guidelines<\/li>\n<li>Prerequisites for submitting a PR<\/li>\n<li>How to add your change to their documentation<\/li>\n<li>A checklist for contribution<\/li>\n<li>Explaining the project\u2019s architecture and setup<\/li>\n<\/ul>\n<p>This document can be as simple as a few notes, or it can be so robust that it takes you a little while to read through it all (like <a href=\"https:\/\/github.com\/atom\/atom\/blob\/master\/CONTRIBUTING.md\" rel=\"noopener\">Atom\u2019s Contributing guide<\/a>, for example).<\/p>\n<p>For larger projects, it makes sense to communicate contributing guidelines up front because <abbr>PR<\/abbr>s and issues can pile up and be a real drag on a maintainer&#8217;s time, sorting through contributions that might be out of the project&#8217;s scope. Make sure to take some of your own time reading through this guide if it exists because your <abbr>PR<\/abbr> will require some of the maintainer&#8217;s time as well.<\/p>\n<h3>Look through the existing issues and <abbr>PR<\/abbr>s<\/h3>\n<p>Before adding a new issue or submitting a <abbr>PR<\/abbr>, it\u2019s good to check what else is out there. You might find someone has already asked about the same thing, or submitted something similar. You can check in the project&#8217;s search box &mdash; I usually search through issues that are both open <em>and<\/em> closed, as it\u2019s important to know if someone already raised my concern and perhaps the maintainer decided to go in another direction. Again, it&#8217;s about saving both you and the maintainer time.<\/p>\n<figure><video autoplay controls src=\"https:\/\/css-tricks.com\/wp-content\/uploads\/2019\/08\/filters.mp4\"><\/video><\/figure>\n<h3>Submit an issue<\/h3>\n<p>Submitting issues is a core part of the <abbr>PR<\/abbr> submission process. They provide an opportunity to articulate the situation, establish context around it, and provide a forum for discussion that can be attached to the <abbr>PR<\/abbr> itself.<\/p>\n<p>When submitting an issue, I like to write out what my concern is and then re-read it as if I was on the receiving end. People are human &mdash; even if what you say is technically correct, you\u2019re not likely to get buy-in for your idea if your tone is off-putting. Consider this: you may be asking for someone to do a lot of work in their spare time. If someone asks you to do work on a Saturday, are you more likely to do so if they ask respectfully with condescension? You get the picture.<\/p>\n<p>When submitting an issue, make sure you give them all the details they need to get the work done. Some things you might note:<\/p>\n<ul>\n<li><strong>If it\u2019s a bug,<\/strong> then what environment you\u2019re seeing the problem in? Is it development or production? Perhaps somewhere else?<\/li>\n<li><strong>If it\u2019s a feature request,<\/strong> then explain the problem. Sometimes framing this from the perspective of the end user in the form of user stories can be helpful, both to conceptualize the situation and abstract it from any personal feelings.<\/li>\n<li><strong>If it\u2019s a general question,<\/strong> then state that up front so the maintainer can avoid spending time trying to figure out if you\u2019re asking for a bug or a feature.<\/li>\n<li><strong>If you\u2019d like to submit a <abbr>PR<\/abbr> to improve on the issue,<\/strong> mention that you\u2019d like to do this, then ask permission to proceed (because sometimes maintainers have other items planned you may be unaware of).<\/li>\n<\/ul>\n<h3>Make considerations before starting work<\/h3>\n<p>You&#8217;re probably eager to start working on your <abbr>PR<\/abbr> by this point. But first, there are still a few customary things to check off before you dig in.<\/p>\n<h4>Ask first<\/h4>\n<p>I\u2019m a big fan of people asking in an issue if a <abbr>PR<\/abbr> makes sense before they work on one. I don\u2019t hold it as a strict rule, but sometimes I can save them buckets of time and going in the wrong direction if we can clarify what we both want together first. It also helps others know to not implement the same thing (assuming they, too, look through open and closed <abbr>PR<\/abbr>s.<\/p>\n<h4>Use labels<\/h4>\n<figure id=\"post-295015\" class=\"align-left media-295015\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2019\/08\/prs-labels.png?ssl=1\" alt=\"\" data-recalc-dims=\"1\" \/><\/figure>\n<p>If you do submit an issue and everyone agrees a <abbr>PR<\/abbr> is a good idea, then it\u2019s nice for you (or the owner of the repo) to add the label <samp>in progress<\/samp>. You can search labels so it\u2019s really clear to everyone you\u2019re working on it.<\/p>\n<h4>Work in small chunks!<\/h4>\n<p>As a maintainer, it\u2019s frustrating when someone put in a lot of work and submits a giant honking <abbr>PR<\/abbr> that does 10 different things. It\u2019s really tough to review, and inevitably, they\u2019re doing six things you want, and four things you don\u2019t. Not only that, it\u2019s usually spread out over multiple files which is difficult to untangle. I\u2019ve definitely closed <abbr>PR<\/abbr>s with some high-quality code I would like just because it would take forever for to review and manage it. (I will communicate that this is the issue if they would like to resubmit the work as separate <abbr>PR<\/abbr>s, though.)<\/p>\n<p>In my opinion, you have about 1,000% more chance of getting your <abbr>PR<\/abbr> merged and your time spent honored if you split things over multiple, smaller <abbr>PR<\/abbr>s. I love it when people submit a <abbr>PR<\/abbr> per topic. And it can be nice, not required, if each submission is a little spaced out as well to help with the cognitive overload.<\/p>\n<h3>Submit your <abbr>PR<\/abbr><\/h3>\n<p class=\"explanation\">These are the steps I personally use to submit a <abbr>PR<\/abbr>. You can get this done other ways, of course, but I have found the following to be effective in my experiences. Also, anything in the commands that are written in <kbd>ALL CAPS<\/kbd> is information you will need to change for your use.<\/p>\n<p>First off, go to the repo, and fork a copy of the project to your personal GitHub account. Clone it locally and change directory (<code>cd<\/code>) to where it&#8217;s located. (I use <abbr>HTTPS<\/abbr>, but <abbr>SSH<\/abbr> is totally fine as well.)<\/p>\n<pre rel=\"Bash\"><code class=\"language-javascript\">git clone https:\/\/github.com\/YOUR-USERNAME\/YOUR-FORKED-REPO.git\r\ncd into\/cloned\/fork-repo<\/code><\/pre>\n<p>Next up, add a remote upstream to the original branch. This means it will share a connection with that original branch so that you can keep in sync and pull down any updates to the project when they happen.<\/p>\n<pre rel=\"Bash\"><code class=\"language-javascript\">git remote add upstream https:\/\/github.com\/ORIGINAL-DEV-USERNAME\/REPO-YOU-FORKED-FROM.git\r\ngit fetch upstream<\/code><\/pre>\n<p>Now you can create a new branch and give it a name that relates to the <abbr>PR<\/abbr> topic. Note that a maintainer might have a specific naming convention in mind that is documented in the repo.<\/p>\n<pre rel=\"Bash\"><code class=\"language-javascript\">git checkout -b GOOD-FORKIN-NAME<\/code><\/pre>\n<p>Go forth and work on your changes. Be sure to <a href=\"https:\/\/css-tricks.com\/how-to-write-a-git-commit-message\/\">make good commit messages<\/a> along the way:<\/p>\n<pre rel=\"Bash\"><code class=\"language-javascript\">git add -A\r\ngit commit -m \u201cADDING IN A TACO DISPENSER\u201d\r\ngit push origin GOOD-FORKIN-NAME<\/code><\/pre>\n<p>GitHub will see the new fork and prompt you to make the <abbr>PR<\/abbr>, which is a nice, helpful touch. You click the button and fill in details: what issue does it close? you can refer to them by their number and GitHub will automatically associate it: <\/p>\n<p>On the <abbr>PR<\/abbr>:<\/p>\n<figure id=\"post-294889\" class=\"align-right media-294889\" style=\"max-width:450px\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2019\/08\/Screen-Shot-2019-08-24-at-10.55.24-AM.png?ssl=1\" alt=\"Shows a referenced issue on a <abbr data-recalc-dims=\"1\">PR<\/abbr>&#8221; \/><\/figure>\n<p>In the Issue:<\/p>\n<figure id=\"post-294890\" class=\"align-right media-294890\"><img decoding=\"async\" src=\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2019\/08\/Screen-Shot-2019-08-24-at-10.56.55-AM.png?ssl=1\" alt=\"Shows what the reference looks like in the issue\" data-recalc-dims=\"1\" \/><\/figure>\n<p>What are some of the things to note in the <abbr>PR<\/abbr>? These details help the maintainer understand context. These can be all the changes you made, they can be larger strategy or context.<\/p>\n<p>And you\u2019re on your way! &#x1f389;<\/p>\n<p>You may find you need to keep your fork up-to-date with the remote, and pull their changes into yours. To do so, you would run this command:<\/p>\n<pre rel=\"Bash\"><code class=\"language-javascript\">git pull upstream master<\/code><\/pre>\n<p class=\"explanation\">Props to Christina Solana <a href=\"https:\/\/gist.github.com\/CristinaSolana\/1885435\" rel=\"noopener\">for her Gist<\/a> which I\u2019ve used as a reference for years and years now.<\/p>\n<p>Always remember: maintainers are often swamped, sacrificing nights and weekends to keep open source projects active and updated. Being respectful, both in terms of their time, and in tone, can set you up for success in contributing.<\/p>\n<hr>\n<p>Open source can be extremely rewarding! Knowing other people are benefitting and directly using something you contributed can be a great way to give back to the community and learn.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The following is going to get slightly opinionated and aims to guide someone on their journey into open source. As a prerequisite, you should have basic familiarity with the command line and Git. If you know the concepts and want to dive right into the step by step how-to guide, check out this part of [&hellip;]<\/p>\n","protected":false},"author":7699,"featured_media":295024,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"c2c_always_allow_admin_comments":false,"footnotes":"","jetpack_publicize_message":"","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":[]},"categories":[4],"tags":[638,1515,477,5125],"jetpack_publicize_connections":[],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2019\/08\/forked.png?fit=1200%2C600&ssl=1","jetpack-related-posts":[{"id":352569,"url":"https:\/\/css-tricks.com\/better-collaboration-with-pull-requests\/","url_meta":{"origin":294887,"position":0},"title":"Better Collaboration With Pull Requests","date":"October 11, 2021","format":false,"excerpt":"This article is part of our \u201cAdvanced Git\u201d series. Be sure to follow us on Twitter or sign up for our newsletter to hear about the next articles! In this third installment of our \u201cAdvanced Git\u201d series, we\u2019ll look at pull requests \u2014 a great feature which helps both small\u2026","rel":"","context":"In &quot;Article&quot;","img":{"alt_text":"","src":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2021\/09\/Untitled-3-2.png?fit=1200%2C375&ssl=1&resize=350%2C200","width":350,"height":200},"classes":[]},{"id":360607,"url":"https:\/\/css-tricks.com\/open-source-sustainability\/","url_meta":{"origin":294887,"position":1},"title":"Open Source &#038; Sustainability","date":"January 12, 2022","format":false,"excerpt":"It's a god-damned miracle to me that open source is as robust as it is in tech. Consider the options. You could have a job (or be entrepreneurial) with your coding skills and likely be paid quite well. Or, you could write code for free and have strangers yell at\u2026","rel":"","context":"In &quot;Article&quot;","img":{"alt_text":"","src":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2022\/01\/github-commit-activity.png?fit=1200%2C600&ssl=1&resize=350%2C200","width":350,"height":200},"classes":[]},{"id":331233,"url":"https:\/\/css-tricks.com\/continuous-performance-analysis-with-lighthouse-ci-and-github-actions\/","url_meta":{"origin":294887,"position":2},"title":"Continuous Performance Analysis with Lighthouse CI and GitHub Actions","date":"December 23, 2020","format":false,"excerpt":"Lighthouse is a free and open-source tool for assessing your website\u2019s performance, accessibility, progressive web app metrics, SEO, and more. The easiest way to use it is through the Chrome DevTools panel. Once you open the DevTools, you will see a \u201cLighthouse\u201d tab. Clicking the \u201cGenerate report\u201d button will run\u2026","rel":"","context":"In &quot;Article&quot;","img":{"alt_text":"","src":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2020\/12\/lighthouse-scores.jpg?fit=1200%2C600&ssl=1&resize=350%2C200","width":350,"height":200},"classes":[]},{"id":356491,"url":"https:\/\/css-tricks.com\/generate-a-pull-request-of-static-content-with-a-simple-html-form\/","url_meta":{"origin":294887,"position":3},"title":"Generate a Pull Request of Static Content With a Simple HTML Form","date":"November 16, 2021","format":false,"excerpt":"Jamstack has been in the website world for years. Static Site Generators (SSGs) \u2014 which often have content that lives right within a GitHub repo itself \u2014 are a big part of that story. That opens up the idea of having contributors that can open pull requests to add, change,\u2026","rel":"","context":"In &quot;Article&quot;","img":{"alt_text":"","src":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2021\/11\/pull-request-form.jpg?fit=1200%2C600&ssl=1&resize=350%2C200","width":350,"height":200},"classes":[]},{"id":330970,"url":"https:\/\/css-tricks.com\/mdn-on-github\/","url_meta":{"origin":294887,"position":4},"title":"MDN on GitHub","date":"December 14, 2020","format":false,"excerpt":"Looks like all the content of MDN is on GitHub now. That's pretty rad. That's been the public plan for a while. Chris Mills: We will be using GitHub\u2019s contribution tools and features, essentially moving MDN from a Wiki model to a pull request (PR) model. This is so much\u2026","rel":"","context":"In &quot;Article&quot;","img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":318499,"url":"https:\/\/css-tricks.com\/building-a-community-driven-site-with-eleventy-preparing-for-contributions\/","url_meta":{"origin":294887,"position":5},"title":"A Community-Driven Site with Eleventy: Preparing for Contributions","date":"August 19, 2020","format":false,"excerpt":"I've recently found myself reaching for Eleventy (aka 11ty) above all other tools when I want to develop a website. It's hard to beat a static site generator that provides advanced templating opportunities while otherwise getting out of your way and allowing you to just create. One of those sites\u2026","rel":"","context":"In &quot;Article&quot;","img":{"alt_text":"","src":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2020\/08\/11ty-stylestage.png?fit=1200%2C600&ssl=1&resize=350%2C200","width":350,"height":200},"classes":[]}],"featured_media_src_url":"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2019\/08\/forked.png?fit=1024%2C512&ssl=1","_links":{"self":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/294887"}],"collection":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/users\/7699"}],"replies":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/comments?post=294887"}],"version-history":[{"count":10,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/294887\/revisions"}],"predecessor-version":[{"id":295025,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/posts\/294887\/revisions\/295025"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/media\/295024"}],"wp:attachment":[{"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/media?parent=294887"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/categories?post=294887"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/css-tricks.com\/wp-json\/wp\/v2\/tags?post=294887"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}