If you don't already know, GitHub is an incredibly effective way to collaborate on development projects. It provides a place for anyone with an internet connection to share code with the world for free (not to mention the robust supporting tools for source inspection and easy viewing of commit histories). Many large open-source projects have adopted GitHub as their primary home for collaboration and contribution.
But how do you join in and contribute to a project? Sure, you know how to use Git to track changes to files and push those files to a server. But there are major benefits to getting involved in larger open-source projects, and GitHub is arguably the best place to start. Today, we will discuss a few rules of the road for collaborating on open-source projects, and give you the knowledge and intuition you will need to get involved.
Start Small
One of the most important things to understand when getting started with collaboration on open-source projects is to recognize your role. Often, there are plenty of things you as a developer can do that don't involve being an extremely clever programmer. In fact, fear of being an inadequate programmer is often a reason why people don't get involved in open-source projects to begin with. Don't be afraid to start small: instead of trying to fix a major bug or rewriting an entire module, try finding things like documentation inadequacies or cross-device testing and patching, or even simple syntax errors and grammar issues (like this one from GitHub user mzgol).
These kinds of tasks are a good way to get your foot in the door as a contributor to the project without trying to take on more than you can handle. Sign up for CodeTriage to get automated GitHub Issues sent to your inbox. If one hits your inbox that you feel confident you can take on, work on it and send a pull request. (We'll talk about how to do that a bit further down in the post.)
Learn the Ecosystem of the Project
With any collaborative effort, a set of conventions has probably been adopted. This may include a vocabulary set, a way of contributing and formatting commit messages, a certain rhythm of collaborating that the contributors have agreed to, or even syntactic standards that have been established. Before you try to get involved with a project, read all documents related to these things. For instance, GitHub has standardized a CONTRIBUTING.md file (check out the guidelines for getting involved with jQuery for a thorough example). These guides are maintained by the people who also maintain the codebase and the master branch.
Another way of understanding the ecosystem of a project is to simply look at the existing codebase and the git log. Reading through the commit messages and perusing the code style can tell you a lot about a project. Read through the project's documentation, and adopt the vocabulary used so that your contributions maintain continuity and portray a similar voice.
Once you're part of the project's cultural ecosystem, how do you actually contribute code?
The Pull-Request Workflow for Code Contribution
The workflow for contributing code can seem daunting at first. The most important thing to remember is to follow the patterns and standards outlined by the project you are working on (as we have already discussed). The general workflow that GitHub supports is fairly simple.
- Fork the target repo to your own account.
- Clone the repo to your local machine.
- Check out a new "topic branch" and make changes.
- Push your topic branch to your fork.
- Use the diff viewer on GitHub to create a pull request via a discussion.
- Make any requested changes.
- The pull request is then merged (usually into the master branch), and the topic branch is deleted from the upstream (target) repo.
Within this workflow, you may see many variations for any given project. For instance, the naming conventions for topic branches vary. Some projects use conventions like bug_345, where 345 is the id of a GitHub issue that has been filed. Some projects prefer shorter commit messages than others. Here is a series of commands that would complete the workflow above.
Step 1: Forking
A fork is basically a copy of a repository (repo) that sits in your account rather than the account from which you forked the content. Once you have forked a repo, you own your forked copy. This allows you to edit the contents of your forked repository without affecting the parent repo.
To fork a repo on GitHub.com, go over to the repo and click on Fork in the top-right corner of the page.
Create a fork to your account.
Step 2: Cloning
While forking allows you to copy source files from another user's repository to your own GitHub account, cloning a repository means grabbing all the source files and copying them to your computer so you can work with them locally.
Clone the repo using the URL provided in the dropdown that appears after you click on Code:
Using a command-line tool, change into the folder you want to put the source files in and download the repo using the git clone command:
1 |
cd my-project-folder
|
2 |
git clone https://github.com/KingsleyUbah/react.git |
Over HTTPS, you'll be required to authenticate with your username and password before proceeding. You can clone using SSH for a more secure transfer (though you'll need a public SSH key on your GitHub account):
1 |
git clone git@github.com:KingsleyUbah/react.git |
You can also download the source files to your computer inside a zipped folder by choosing the Download ZIP option.
Step 3: Adding the Upstream Remote
Now you have cloned a repo to your local machine and made changes to the files. To tell the Git repository on your computer which remote repository to send the changes to, you use the git remote add command, followed by a custom name for the remote repo and the URL of the repository.
Change into the cloned directory, and then at this point, you can add the upstream remote:
1 |
cd react
|
2 |
git remote add upstream git@github.com:facebook/react.git |
This will add Facebook React's GitHub repository as the remote repo and set upstream as the remote name. By default, when you clone a repo to your local computer, the repo from which you cloned will be automatically set as the remote repository, and origin will be used as the remote name.
If changes are made to the upstream branch, you can pull in those changes from the source and merge them to your local repository, like so:
1 |
git pull upstream master |
Step 4: Checking Out a Topic Branch
However, before you make your own changes, check out a topic branch:
1 |
git checkout -b enhancement_345
|
That way, if you make a mistake that introduces bugs to the code, you can easily destroy the branch and not affect your whole codebase.
Step 5: Adding Changes to the Staging Area and Committing
Now, you can make your changes, add the changes to the staging area, and create a commit that tracks just those changes.
1 |
git add .
|
2 |
git commit -am "adding a full stop to the code of conduct document." |
The commit message describes the kind of change performed on the local repository.
Step 6: Pushing
Next, you'll push this topic branch to your own fork of the project.
1 |
git push origin enhancement_345 |
Step 7: Creating a Pull Request
Finally, you will create a pull request to complete your open-source contribution.
First, go to your fork of the repo. You might see a notice that some pushes were made including the branch and the time it was made, and if so, you can choose Compare & pull request.
Otherwise, you can select your branch from the dropdown below, and subsequently click Pull Request or Compare at the top right of the repo section.
Either of these will take you to a page where you can create a pull request and comment on the request.
From the image above, you can see that the commit message is automatically used as the pull request title, although you can change it. The body of the comment is populated with instructions from React on how to optimize your pull request. GitHub supports Markdown, so you can structure your comment using Markdown and preview it to see the result.
The description of every pull request should contain a summary of all the changes you have made—a checklist may be used to highlight these changes.
This page also includes a visualization of the changes you made. This makes it easy for the project administrator to see what you have done and make easier decisions about whether it is appropriate to merge your commit.
Here we are viewing another change made to a source file in Facebook's React repo. Red indicates the lines where something was removed, green indicates lines where additions were made, and dark green shows the specific characters that have been added (dark red shows the specific characters removed).
If the administrators have questions, they can ask them in the comments; they may also ask you to clean up your pull request and resubmit, and subsequently close the pull request.
Note that it is important that you show the administrators of a project full respect; after all, you can always use your forked version of the code, and if they chose not to pull in your changes, it is because they have the right to do so. Remember, according to GitHub employee Zach Holman's take in "How GitHub Uses GitHub to Build GitHub", pull requests are conversations. This is how they should be treated; instead of expecting your commit to be accepted, you should expect only that it will open a conversation about the code that you wrote.
GitHub Issues + Pull Requests = Project Management Zen
GitHub offers GitHub Issues, which is a robust way of creating documented, interactive, automated conversations about bugs or features for any given project. While Issues can be disabled, it's enabled by default. There are a lot of awesome features that Issues has built-in, but one of the most important features is its integration with pull requests. A user can refer to an issue in their commit message by simply including the issue's numerical ID in the commit message. For instance:
1 |
git commit -am "Adding a header; fixes #3" |
This commit message would automatically mark issue #3 as closed when its associated pull request is accepted. This kind of automation makes GitHub a wonderful tool for development project management.
Issues have labels, and a great thing about these labels is that you can use them to filter out the kinds of bugs that you want to solve. So if you want to find something more challenging, easier, or a specific kind of bug, you can use the issue filter functionality. If you are looking for something easier, for example, a good label to seek out is the good first issue label.
To filter out a particular kind of issue, you simply click on the label. To create a new issue, click on New Issue on the top right and you may be provided with some templates to choose from (depending on the project).
These issues typically come with a description field that is populated with instructions to guide the project contributor on raising a valid issue.
If your issue doesn't fit any of the categories provided, open a blank issue. Here you set your title and a comment describing the issue you are raising.
The issue description can be styled using Markdown, and you can preview your Markdown by clicking on the Preview tab.
Once you submit the issue, other contributors will be able to get involved in the conversation by leaving comments.
Seek Out Secondary Channels of Collaboration
Don't get caught up thinking that the only way you can contribute is through pull requests. Often, large open-source projects benefit from many different kinds of collaborative work. For instance, a project like Ruby on Rails was famous for its community; this community would answer questions on forums and in IRC chatrooms to help build knowledge about the framework, and also would help drive the future direction of the framework by talking about ideas and uncovering bugs.
These channels of collaboration are usually opened up as support environments as mentioned before, such as forums and chatrooms. There may also be email chains, meetups, or conference calls that help define the project's direction and create a lively, productive community around the project. Without this kind of community, pull requests are far less effective.
Most of All, It's About Your Attitude
Remember, open source is driven by people who have the attitude that sharing knowledge and building collaborative intelligence is a worthwhile endeavor. Your involvement in these projects will be most effective if you approach a given project with the inquisitive attitude that asks, "How can I help?" rather than a closed attitude that says, "I'm going to help however I want." People in the open-source world want to work with people who are genuinely driven to help others.
Conclusion
If you are interested in getting involved in an open-source project, great! Remember, if you approach the project with the right attitude and start small, you could see your name on pull requests merged into code that is distributed to people all over the world and used every day.
Take the time to learn about the project and the people who are involved with it. Develop a genuine interest in helping the project become better. The power of GitHub and the open-source world are continuing to grow every day; start collaborating with other developers, and you can be a part of that world!
This post has been updated with contributions from Kingsley Ubah. Kingsley is passionate about creating content that educates and inspires readers. Hobbies include reading, football and cycling.
