When you’re first learning and navigating the website, you should always remember that the goal of GitHub is to provide a secure, collaborative environment where newcomers and experts alike can design, develop, and deploy any software, from programs that say “Hello World” to code that sequences human proteins to help cure major infectious diseases around the world.
To be a part of this community, you just have to be an effective communicator, find and create collaborative projects, and know how to find the help you need, when you need it.
Finding out more on GitHub.com
One of the most important things to know how to do is to find more information on GitHub when you need it.
GitHub is always evolving and changing, and by the time you’re reading this Cheat Sheet, Git may have new features, new applications to integrate with, or new projects that are popular. It is important that you remember how to learn more about GitHub as a tool.
GitHub docs
GitHub has an extensive list of docs. You can either use the search bar at the top of the page to find a specific topic, or you can choose the GitHub product that you have a question about (which includes GitHub.com) and then browse topics that are popular among GitHub users.
GitHub docs are often effective for folks who have a specific question. If you want to generally learn how to use the products, GitHub docs may be more difficult for you to navigate.
At the bottom of each page on the Docs site, however, is a link to the GitHub support page, along with guidelines on when, who, and how to contact for various problems you may encounter.
GitHub guides
GitHub has also produced a number of guides to help with common getting started actions. If you go to the Get Started web page, you can find guides and getting-started docs that help you get started with many of the features of GitHub.
Think of these guides as GitHub’s version of a cheat sheet. They can be really effective if you have a particular goal, as the topics range from how to fork a project to how to be social on the platform.
One of the most important guides on this page is the GitHub flow guide. This guide explains the entire GitHub flow, from writing and committing code to creating and merging pull requests.
GitHub professional training
If you’re looking for a more hands-on and guided introduction to GitHub, you can get the help of GitHub Experts for your company or team through the professional training that GitHub offers.
GitHub Skills
Probably one of the most effective learning tools on GitHub, the Skills are interactive experiences on the actual GitHub.com platform that allow you to try complex workflows, such as creating and reviewing pull requests, starting a community on GitHub, or even setting up continuous integration on your project.
Communicating effectively in GitHub repositories
Whether you’re contributing to a large GitHub open source project, working with a small group of people, or even working on a project completely by yourself, it is critical that you approach your GitHub repositories as living documents of your project.
As repositories get larger and code gets more complex, learning how to communicate asynchronously through code, issues, and pull requests becomes a skill that is absolutely critical to succeeding not only on GitHub, but in the field of computer science as a whole.
The number one thing to remember is to document. Document everything that you do, such as:
Code comments
Comments throughout your code offer an English description of what your code should be doing. Comments can help you (or others) identify when the code written doesn’t accomplish what was expected.
By keeping comments up to date as code changes, you make it easier for others (or your future self) to know what the code is meant to do and make it easier to identify where goal doesn’t meet actuality.
README
The README is the front page of your entire project. Anytime something changes about the way the code runs or how to contribute to the code, you should always update the README. The README is the first place people come when they’re new to your project, so you want to have a descriptive summary of the software from both a user’s and contributor’s perspective.
Docs
Writing docs on your software can be a very effective way to avoid confusion for both users and contributors. You can use documentation generators, such as Javadocs, or simply be disciplined about writing documentation about any new or modified code in your project.
Issue descriptions
If you’ve found a bug, the issue you create should always include a detailed description of exactly what error you found. You should include the version of the software or the branch that you were on, operating system version, and other relevant software versions, such as browser. It can also be useful to include screenshots.
If you have an idea for a future feature or a modification in the software, make sure to be as detailed as possible. Be respectful with your asks and recognize that the main developers on the project may not agree with your suggestion, or it may not be a priority for them. In other words, don’t try demanding that something you want be made immediately, but rather focus on the goal of being a collaborative member of the project.
Pull request description
Pull request descriptions should reference issues that they’re fixing. You can directly reference the issues by specifically tagging them. If you add “Closes” before the issue link, then when the pull request is merged, the issue will be closed with it.
In addition to the issue(s) that the pull request addresses, you should always have a clear, detailed description of the changes you made, how they may affect other parts of the software, unit tests you ran, and screenshots that show the changes made.
You can also open a pull request when you first start tackling an issue and use the description as an outline for what you need to do to complete the task. You can have a literal checklist, which can help collaborators know where you are in the solution and have a better grasp on how quickly you may be done.
Navigate an open source software project on GitHub
When you first come across a GitHub open source software (OSS) project, you should spend a good amount of time exploring the project, documentation, and guidelines before you attempt to contribute to the project.
OSS maintainers spend a lot of their time and energy ensuring that documentation is kept up-to-date and the community is aware of the new features or bug fixes that are a priority. Spending time orienting yourself with the software and the community of a particular project will increase your chances of being able to actually contribute to the project.
It is also an important part to becoming a member of that community. Coming in as an outsider suggesting changes (either through issues or pull requests) without having the background on the project will make it seem like you aren’t invested in the project.
Approach projects as a learning experience, not an opportunity for you to teach. With time, you probably will have your chance to make an impactful change and probably teach others.
There are a few places to start when you’re orienting yourself to a GitHub project:
- README: Make sure you’ve read through the README, where you can find a lot of useful information about compatibility and how to get started as a user or contributor for the software.
- Getting Started docs: Often, projects will have some guidelines on how to get started either using or contributing to the project. If your goal is to contribute to the software, fork the project and get it running on your local machine.
If you have trouble, review docs or issues (even issues that may be closed) before opening a new issue with your question. It’s likely someone else has run into a similar problem, and the answer is already somewhere on the repo. If it seems to be a major issue, you may even make a suggestion to modify the docs to include the fix.
- Contributing guideline: Most projects will have a contributing guideline doc, which often includes a Code of Conduct. You should take the this very seriously. Writing code isn’t enough; you have to be willing to join the community and be a positive member.
Poor behavior will (and should) be reported to the maintainers. The contributing guidelines also often include naming conventions, the decision-making process, the workflow between maintainers and contributors, and general style guides.
- Existing issues and pull requests: Finally, before getting started, read through some existing issues and pull requests to understand how the community communicates. This can both help you better interact with this particular community, as well as maybe make a decision that this community isn’t one that is right for you.
You can also see what the workflow of top contributors on this project is. For example, are pull requests often large with a lot of major changes, or small with very focused goals?