Stepping into the diverse world of open source might seem overwhelming for newcomers. This blog is here to guide first-time contributors through the basic essentials, ensuring they can make their mark with confidence. From basic git commands to navigating GitHub PRs, issues, merge conflicts, and best practices, this blog will serve as the perfect introductory beginner guide.
Table Of Contents
- What Is Open Source?
- Why Open Source?
- Git
- GitHub
- Understanding The Steps In Making A Contribution
- Merge Conflicts
- Best Practices
- Common Roles
- CLAs
- What's Next
- About Me
What Is Open Source?
Open Source/ Open-Sourced Software is software that is freely accessible for users to view, modify, and distribute according to its license agreements. Open Source promotes transparency, collaboration, and inclusivity among developers. As developers, we come together to solve problems, add solutions and in return create efficient software for other developers.
Why Open Source?
Open Source has a plethora of benefits, if you are a project maintainer or a developer, the open source community can assist you in incredible ways.
As a project maintainer, open-sourcing your software can bring in new feature ideas, implementations, and resolutions to pesky bugs that you might not have even considered. As help from seasoned and beginner contributors pour in, you'll be able to maximize the potential of your software to a whole new level, making it robust, innovative, and valuable to users worldwide while promoting transparency and collaboration.
As a developer, open source software (OSS) offers a rich opportunity to contribute and analyze software used by a wide variety of users. If you're someone who's naturally curious or loves problem-solving, debugging, and creating solutions, you'll appreciate the transparency that OSS brings. It allows you to delve into the inner workings of software, understand its complexity, and collaborate with others to enhance it.
Moreover, open source presents an excellent chance to upskill and network with talented developers worldwide. By engaging in OSS projects, you can expand your technical skills, learn from others, and build valuable connections within the developer community. Together, you can make a meaningful impact by improving software, fixing bugs, and implementing new features that benefit users globally.
Git
In simple terms, Git is a version control system that allows you to manage your source code during development. Its key feature is its ability to track and retrace the changes in your code.
As a beginner contributor, you must have git in your local setup for development. The installation steps are straightforward.
Installation
1.Navigate to git's official website to download the software according to your machine and follow the steps: https://git-scm.com/downloads
2.After the installation, confirm if you have git by running the below command.
git --version
And that is it, you now have git setup. Git will help us locally to track code changes.
Necessary Configurations
1.Configure your username with the command
git config --global user.name "Your Name"
2.Configure your email address with the command
git config --global user.email "your@email.com"
Commands
In this tutorial, I'll only be covering the basic commands needed to commit to an OSS repository. Please go ahead and explore the possibilities with git by yourself.
1.git init
To initialize git in your local project. This is not necessary if you are contributing to a project on GitHub already. If you are thinking about open-sourcing your software then you would need this command to initialize a Git project before pushing it to GitHub.
git init
2.git clone
To clone a remote repository(a remote repository is a project directory or structure that is hosted on another platform, in our case GitHub, and is not in our local). With git clone you can get a copy of that code in your local setup and start analyzing and working on it.
git clone <remote-repository-url>
3.git status
To display the current state of the repository. It will show you the modified/deleted files in your local. Highlighted in red indicates the changes are not yet in stage while green indicates it has been staged.
git status
4.git branch
Switches to an already existing branch(a branch is a parallel line of development that diverges from the main/master of a project).
git branch <branch_name>
5.git checkout
By default, every repository includes a main/master branch, typically containing the code used by end users. Now, imagine you and another developer aim to add two distinct features to the project. The optimal approach is to create two separate branches. Using git checkout, you can duplicate the main branch's code at that point in time, allowing you to work independently on your respective features. This method keeps your code isolated, ensuring no disruption to the main branch or the other developer's work. Upon completing your features, both of you can submit merge requests to integrate them into the main branch.
git checkout -b <branch_name>
The -b flag essentially tells Git to create a new branch instead of just switching to an existing one.
6.git add
To add all your local changes and move them to stage. Staged changes are changes that are not committed to the branch you are working on yet.
git add <filename>
git add <filename1> <filename2>
git add .
7.git commit
To save your changes to the branch. git commit will save the changes that are staged, i.e. the files that were added by git add.
git commit -m <message>
The -m flag in Git commit commands is used to specify a commit message inline with the command itself.
8.git push
To push commits to the remote repository.
git push origin <branch_name>
9.git pull
To pull changes from a branch into the working branch.
git pull origin <branch_name>
GitHub
GitHub is a platform that provides hosting for software development projects using the Git version control system. It provides a number of features and tools to make code deployment, project management, and developer collaboration easier. In short, Git provides you the feasibility to control and manage your code locally and GitHub is a platform where you host your software for other developers to discover, explore, and contribute.
Setup
There is no setup, all you need to do is navigate to https://github.com and create an account if not already.
Terminologies
Repository : It's where the project's source code and related files are stored along with its version history. With GitHub, every repository has access to a variety of features such as actions, insights, and more. I encourage you to explore these additional functionalities as well.
If you are a potential maintainer you can create a repository from your GitHub dashboard and follow the on-screen steps.
Pull Request : A pull request is a request to merge changes from one branch into another branch. It allows developers to review, discuss, and collaborate on proposed changes before merging them into the main codebase. A pull request can be in the status of open, draft, and closed.
Issues : An issue is a feature request, bug report, or task associated with a repository.
Fork : Forking is the act of creating a copy of someone else's repository for which you don't have ownership rights such as creating branches, adding commits, etc, into your own GitHub account. Forking will create a copy in your ownership and will allow you to make changes to the codebase independently and propose those changes back to the original repository through pull requests.
Ideally, you would fork a repo, create a branch, make changes, commit, and raise a pull request to the maintainer of the project. We will go into detail on contributions in the upcoming sections.
Clone : Cloning is the process of creating a local copy of a repository on your computer. It allows you to work on the project locally, make changes, and push those changes back to the remote repository.
Branch : A branch is a parallel line of development that diverges from the main/master of a project. GitHub gives you the flexibility to create branches and view them.
Understanding The Steps In Making A Contribution
Let's assume below is the repo I would like to contribute to. This is how I would go about it.
Step 1: I will first fork this repo, and create my copy in my GitHub account. Click on the fork button on the top right corner of the repository. Once clicked, you should see the below screen, click on create fork.
Step 2: In my version of the project, I will now copy the clone URL to set up local development.
I will open a terminal in a preferred source-code editor such as VS Code in the preferred destination and run the below command.
git clone <remote repository URL>
Below should be the output. As you can see I was easily able to get the code and repo structure to my local environment.
Step 3 : I will create my branch using git checkout
git checkout -b <branch_name>
Step 4: I will start making my changes. Once done, I will view my modified files by
git status
If you are using VS Code you can also see these changes on the GUI on the left side.
Step 5: I will now stage and commit my changes.
git add .
git commit -m "update readme"
Step 6: Now I will push my branch to my forked remote repository.
git push origin feature_update_readme
Step 7: Let's navigate back to our forked repository on GitHub.
Step 8: Click on Compare & Pull Request, add sufficient details on the screen, and raise your pull request. Make sure your base and head are set correctly.
Wait for the maintainer to review your PR(Pull Request) and merge. If the maintainer asks for changes, sync your fork and take a fresh pull of the main branch of your forked repo into your working branch(feature_update_readme).
Run the below command after syncing the fork.
git pull origin main
Make the requested changes locally and push again. You do not/ cannot raise a pull request again, the changes will be updated in your before-opened pull request itself as long as you do not close it.
Merge Conflicts
Merge conflicts occur when there are conflicting changes between branches being merged. This happens when changes made to the same part of a file in different branches cannot be automatically resolved by Git. As a developer, you will have to manually resolve such conflicts.
GitHub gives you the option to resolve conflicts on the platform itself, but if there are complicated changes in too many files, it's better to resolve them locally.
First, sync your fork and take a fresh pull of the main branch of your forked repo into your working branch(feature_update_readme).
git pull origin main
You should see the below output.
-
git config pull.rebase false: By default, when you run git pull, Git will try to rebase your changes on top of the changes fetched from the remote repository, rather than creating a merge commit. Settingpull.rebasetofalsemeans that Git will perform a merge commit instead of a rebase when you pull changes. -
git config pull.rebase true: With this configuration, git pull will attempt to rebase your changes on top of the changes fetched from the remote repository. This can result in a cleaner and linear history, as it avoids creating merge commits. -
git config pull.ff only: This command sets the configuration optionpull.ffto only. This option tells Git to perform a fast-forward merge whenonlypulling changes. A fast-forward merge occurs when your local branch has not diverged from the branch you're pulling from, so Git can simply move the pointer of your local branch forward to incorporate the new changes.
You can choose any of the merging strategies based on your use case. In this example, I'm going with git config pull.rebase true
As you can see in the GUI, the files affected by the conflicts are mentioned with red !(exclamatory points). You can use that to identify conflicted files and resolve them.
Choose to accept the incoming change or current change or both. Once done, stage(git add .), commit and push your changes.
Best Practices
Here below I have jotted down some of the basic best practices I have seen community members follow and I personally follow.
1.Maintainers
- As a maintainer open-sourcing your software, make sure your repository has a CONTRIBUTING.MD, README.MD, CODE_OF_CONDUCT.MD and LICENSE(if needed).
- Create Issue templates and Pull Request templates for contributors to utilize.
- Create relevant labels for issues and pull requests.
- Utilize GitHub bots, Actions, and Projects to manage your repository better.
- Add relevant
good first issuesto invite contributors. - Be active in reviewing issues and pull requests and close them if you do not plan to implement them with relevant comments.
- Interact with your contributors through GitHub discussions, discord, slack, etc. Create a community for the developers who contribute to your software, and conduct engaging discussions.
2.Contributors
- Make sure to always read CONTRIBUTING.MD, README.MD, CODE_OF_CONDUCT.MD and LICENSE of the repository you are contributing to.
- Always follow standard coding practices while coding.
- Don't create unnecessary/spammy issues or pull requests.
- Add sufficient screenshots and explanations in your issues and pull requests.
- Always link or mention the issue number/id in your pull request.
- Always claim issues(ask it to be assigned to you) before you start working on a pull request.
- Be active in the community group to make the best out of it.
- Always prefix pull requests, issues and branches with the type of task
doc,feature,bug,etc. - Mention issue id's in pull request descriptions.
- Be active in responding to review comments.
Common Roles
Owner: The owner of the repository is in complete control of it. They have the ability to modify the repository's name, add collaborators, change ownership, and even completely remove the repository. Additionally, owners have administrative access to pull requests, settings, and issues.
Collaborator: Users who have been authorised by the owner or an administrator to read and write to the repository are known as collaborators. They have the ability to manage problems and project boards, push changes, establish branches, and initiate pull requests. Collaborators are unable to add new collaborators or modify repository settings, nevertheless.
Contributor: Users who have forked the repository and submitted pull requests are considered contributors. Although they cannot directly write to the repository, they can still suggest modifications by submitting pull requests. The modifications made by a collaborator or owner are included into the repository after the pull request is merged.
Viewer/Read-only: The repository's contents can be viewed by users with read-only access, but they are unable to make any modifications. They are unable to submit changes or start new branches, but they can read the code, view problems and pull requests, and download the contents of the repository.
Assignee : Assignee is the individual who is assigned to take responsibility for the issue or pull request.
Reviewer : Reviewer is the individual who is assigned to review and approve the pull request.
CLAs
CLA stands for Contributor License Agreement. It's a legal agreement between the contributor of code to a software project and the maintainers of that project. Not every repository has it, and if you ever come across it yourself, here's what you should know.
Contributors must agree to the terms of the CLA before their contributions are accepted into the project. The CLA outlines the rights granted by the contributor to the project maintainers and the community.
Contributors who sign the CLA give the project maintainers permission to use, alter, and distribute their code under the terms of the license they have chosen for the project. These rights contribute to the project's ability to accept and disperse contributions without violating the law.
If you are a new contributor and you are asked to sign a CLA, make sure you understand the terms of the agreement before you do so.
What's Next
If you've read this far, first of all, thank you! I hope this blog equips you with the confidence to make your first contribution. I'll be jotting down helpful resources in this section for you to explore and get some hands-on experience.
-
GitHub Search WebApp :
Search for
good first issuesby updating labels and other relevant information in the form. - GitHub Explore : Leverage GitHub's own feature to browse and find interesting repos.
- Good First Issue : Browse open good first issues
- Up For Grabs: Find open issues that are ready for contribution.
- Open Source Diversity: For helpful information and resources.
- CodeTriage: To subscribe to your favorite open-source projects and get a new open issue from them in your inbox every day.
- First Timers Only : For helpful information and resources.
About Me
Hi, I'm Everly 👋 .
Passionate about software development and emerging technologies, I'm deeply committed to exploring diverse fields and driving innovation. My journey includes contributions to renowned open-source programs like Google Summer of Code with Apache and an externship with GitHub via Appwrite, where I honed my coding skills and cultivated a robust problem-solving acumen.
I'm enthusiastic about sharing knowledge and learning from the community. I embrace speaking and mentoring opportunities to foster collaboration and innovation within our community.
Top comments (16)
I have some issues. Please, how do I delete some files in my repository ? I searched for it during last hour. Is it impossible to delete all repository and rebuild one another ?
It is possible to delete the entire repository if you want.
https://github.com/{username}/{repository-name}/settings, scroll till the end, highlighted in red you should find the option to delete the repository entirely.Morning, I delete repositories. Then, I create new repositories. I want to create newly files. I'm not finding such as previously "Add new file" in respective repositories
. Why ? It's very annoying. I have wasted 1 hour. Why ?
Thank you too much. I just work on it now. You may either delete entirely repository. Well.
you can always choose to delete those files locally and just push the changes. but if you want to delete those files through github, then just navigate to the file , click on the horizontal three dots on the right and delete the file, it will be highlighted in red.
Thank you too much. Indeed, i just see it now. But I experience that with this method, file doesn't disappear. It seems that it remains inside repository. The first method is better. Cool.
Thank you, great article!
Thank You !
Hi Everly, you've done a great job for novice developers. Every developer should have the basic knowledge of.git GitHub to this extent at least.
Thank you !
This is exactly what every developer needs. A great read for noobies as well as a refresher for other devs.
Thank you !
Really great article!
Thank you, appreciate it !
most horsecrap article on the topic, why you have to confuse b/w open source and source code management
OSS is about software that's freely accessible to people. If a person wants to contribute to it, they will need to know source code management. So, yes this article in a way covers source code management but only in a brief level to make a quality first contribution and is intended for beginners. I have made it pretty clear in the intro that it is for first-time contributors, to just get started.
It talks about CLAs and provides resources for open-source enthusiasts to make their first mark. You can't expect me to write an article for first time contributors without talking about source code management can you? What type of beginner friendly article would that be?
Some comments have been hidden by the post's author - find out more