Best Recommended Practices for Beginners on GitHub
Read on to check out essentials ahead of Hacktoberfest for first-time contributors!
Table of contents
- Prerequisites
- How are Git and GitHub different?
- Recommended Practices
- Ending Notes
GitHub is a powerful platform for visualizing version control and enabling code collaboration amongst developers. With over 100 million developers on the platform, it’s the leading cloud-based hosting for Git repositories. In this blog, let’s look at the differences between Git and GitHub and learn about some of the best GitHub practices recommended for beginners.
Prerequisites
To follow along, make sure you have the following things in place:
An account on GitHub. If you haven't created one yet, you can do so by following this link.
Git installed on your system. The setup instructions on this link will help you install Git on your workstation.
How are Git and GitHub different?
While Git is a distributed version control system, GitHub is a platform designed to offer a graphical user interface on top of Git, including features like code collaboration, project management, and visualization of changes, among many others.
A VCS allows developers to save snapshots of their project history to enable better collaboration, revert to previous states, and recover from unintended code changes, and manage multiple versions of the same codebase.
In simpler terms, Git is a CLI (command-line interface) tool for managing local changes. In contrast, GitHub is a platform for collaboration in a remote environment, aiding social coding.
Recommended Practices
Let's dive back into the recommendations and explore each one thoroughly, along with the reasoning on why they might come in handy.
1. Master Basic Git Commands and Concepts
To best use the platform, it’s crucial to know the concepts of Git and GitHub alongside the most frequently used commands, as they form the core features of GitHub. Here’s a brief overview of both:
Git (and GitHub*) Concepts
| Term | Definition |
| Repositories | A storage location for your codebase containing all the files and metadata pertaining to the project. |
| Branches | A separate line of development within a repository wherein you can create segregation for running experiments without breaking the stability of the main line. |
| Commits | A snapshot of your changes in the repository that defines who made the changes and what the changes were. |
| Issues* | Used to report bugs, request features and enhancements, and track tasks and progress on actionable items. |
| Pull Requests* | A method to propose changes to the codebase, requesting code review and collaboration. |
| Merges and Conflicts | Merging is the process of introducing changes from one branch to another, typically done to implement features or fixes. A conflict arises when two branches are too distinct to be merged and it requires manual resolution to implement changes. |
Git Commands
| Command | Definition |
git init | Initializes a new Git repository in your current directory. |
git clone | Copies an existing Git repository from a remote server to your system. |
git add | Stages changes (new, modified, deleted files) to be included in the next commit. |
git commit | Records the staged changes with a descriptive message in the repository's history. |
git push | Uploads your local commits to a remote repository. |
git pull | Fetches and merges changes from a remote repository into your local branch. |
2. Configure Git Client Correctly
The most common mistake beginners make is not setting up the Git client correctly on their local system, which makes their contributions seem like they were committed by an unrecognized author. Configuring Git client the right way is important for recognition, ensuring all your commits are attributed correctly to your identity, and tracking your contributions, especially on collaborative projects.
To set your author information, which is your name and email address, use the following commands, replacing the variables with your details:
git config --global user.name "Your Name"
git config --global user.email "youremail@example.com”
To maintain consistency across your repositories, make sure you use the same email associated with your GitHub Account across all the systems and environments you use.
3. Protect Secrets
A good chunk of the projects we work on today use or hold sensitive information such as SSH Keys, API Keys, Private Tokens, or even passwords. Commonly referred to as secrets, ideally, they should not be visible on your GitHub Repository as they can be misused in multiple ways.
The best way to handle secrets is to treat them as environment variables and create a separate .env file to store any keys and tokens. The .env file can be added to .gitignore to prevent the file from leaking into the repository and becoming public. You can read about the steps to do so here.
4. Use Branches Effectively
It is always recommended to have a clean, stable main branch on any repository for proper collaboration. Branches are handy when you want to experiment with bug fixes and new features without affecting the workings of the main branch or breaking codebases. While you’re at it, it’s also helpful to have meaningful names for branches that describe the purpose of segregation.
You can also take a look at the concept of Protected Branches and Branch Protection Rules on GitHub to see how you can protect specific branches from random commits.
5. Draft Descriptive Commit Messages
Commit messages are a part of the git commit command, added with the -m flag to describe the changes made with the commit. It is highly recommended to write crisp and clear commit messages to help other collaborators understand the changes.
It is also recommended to follow the conventional commit format, which you can find here.
Note: Git does not allow you to push commits without a commit message. The message can be empty but you'll still need to specify it using git commit -m "". This is not recommended as without any context, it will be difficult to know what changes have been made without going through the code. It also makes tracking difficult, nullifying the point of using Git.
6. Have a Consistent Directory Structure with Recommended Files
An integral part of repositories on GitHub are files like README.md, LICENSE.md, CONTRIBUTING.md, and .gitignore. These files, especially README.md provide essential details about the repository including installation instructions, contributing guide in case the repository is open-sourced, and if the contents of the codebase can be used by other developers.
The first three files are written in Markdown.
If you plan to work on an open-source project, check out this guide to ensure that your license aligns with how you want the source code to be utilized. Here’s another quick guide to help you draft better README files for your repositories.
While you’re at it, another recommendation is to house media like images and other assets in a dedicated directory inside the repository, preferably naming it assets or repository-assets if the media is just for the README.md files in the repository.
7. Use Pull Requests and Issues Frequently
Pull Requests on GitHub come in handy while collaborating on larger codebases. Proposing changes via Pull Requests allows maintainers to check and review changes before they are merged, minimizing code breakages significantly. Pull Requests also help with receiving feedback and code reviews in case the commits are not up to the mark and require changes before they are pushed to the main branch.
In case you don’t have any code recommendations but want to report or track bugs, request new features or enhancements, or have other concerns, you can use Issues. Issues help create workflows and often lead to better project planning. You can read more about the capabilities of Issues here.
8. Grab the Right Tools and Resources
Many resources are available to help you master Git and GitHub. With the recent advent of AI, there are more tools than ever to help you dive deeper into codebases and understand how things work under the hood.
Some other tools and guides you would want to explore are as follows:
Visual Studio Code: A highly customizable IDE with a rich extension ecosystem you can benefit from as a budding developer.
GitHub Desktop: If you’re uncomfortable using command line tools, you can head over to GitHub Desktop. It’s great at simplifying Git operations with just a few clicks.
GitHub Documentation: You can learn about features and product capabilities and find more resources in GitHub’s official documentation.
Good First Issue: Get cracking on actual open-source repositories waiting for your contributions.
Ending Notes
Mastering GitHub's best practices is a must for any developer looking to contribute effectively to projects, whether beginner or veteran. By following these recommendations, you'll not only improve your own workflow but also contribute to the growth of open source.
With Hacktoberfest right around the corner, there's no better time to put these practices into action and start making meaningful contributions to open-source projects!