Entering open source can feel daunting. The sheer fear of running the wrong command in your terminal, breaking a codebase, or looking inexperienced stops many capable developers from making their very first contribution. This is the "Git Scares"—and every engineer has felt it.
This guide eliminates that barrier. Instead of throwing you into complex codebases and messy bug fixes, Part 1 walks you through the cleanest, zero-risk way to submit your first Pull Request: adding your name to CONTRIBUTORS.md in an active community repository (PinpointPro).
By the end of this tutorial, you will have completed the full professional Git lifecycle—forking, cloning, branching, committing, pushing, and opening a Pull Request—without the risk of breaking production.
What You Need Before You Start
- A free GitHub account
- Git installed on your computer (Download Git)
- A terminal (Git Bash or PowerShell for Windows, or the built-in Terminal for macOS/Linux)
- A simple text editor (Notepad, VS Code, or Vim)
Take a breath, open your terminal, and let’s make your first contribution!
STEP 1
Fork the Repository on GitHub
Forking gives you a space you fully own — you can experiment, commit, and break things without touching the original project. We are working with a repository from [https://github.com/raphgm/pinpointpro] .Forking also creates a personal copy of the PinpointPro repository under your own GitHub account, with its full commit history.
-1. Open your browser and go to: https://github.com/raphgm/pinpointpro
-2. Click the 'Fork' button in the top-right corner
-3. Leave all settings as default and click 'Create fork'
-4. GitHub will redirect you to your fork at: https://github.com/YOUR_USERNAME/pinpointpro
STEP 2
Configure Your Git Identity
Without this, Git cannot create a commit — it will error and ask you to configure your identity first. Your email must match your GitHub account so your commits are correctly linked to your GitHub profile and appear in your contribution graph.
USE
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --list
STEP 3
Clone Your Fork to Your Machine
All Git commands must run from inside the repository folder. The clone creates a full local copy — including commit history — so you can work offline.
USE
git clone https://github.com/YOUR_USERNAME/pinpointpro.git
cd pinpointpro
STEP 4
Wire Up the Upstream Remote
- Add the Upstream Remote -The upstream remote lets you pull those changes before branching — preventing stale-branch conflicts.
git remote add upstream https://github.com/raphgm/pinpointpro.git
- Verify Both Remotes Exist -Never assume a command worked — always verify. A misconfigured remote is one of the most common sources of failed pushes and unexpected PR targets.
git remote -v
- Sync Your Fork with Upstream -Fetches all new commits from the upstream repo, then merges them into your local main branch so your fork is fully up to date.
USE
git fetch upstream
git checkout main
git merge upstream/main
STEP 5
Create Your Feature Branch
Feature branches isolate every piece of work from main. If your PR is rejected, nothing is affected. If a colleague opens a PR at the same time, there's no conflict. This is non-negotiable in every professional engineering team.
USE
git checkout -b feature/yourname-add-contributor
git branch
STEP 6
Choose Your Contribution & Make It
- Open the file:
- mac/linux: vi CONTRIBUTORS.md
- windows (Git Bash): notepad CONTRIBUTORS.md
windows (PowerShell): notepad .\CONTRIBUTORS.md
Append this block at the very bottom :
Your Full Name
GitHub: @your-username
Contribution:
Date: YYYY-MM-DD
USE
git diff CONTRIBUTORS.md
- Shows the differences between your working files and the last commit
STEP 7
Stage & Commit Your Work
- Stage Your Changed Files-Staging lets you craft precise, single-purpose commits , intentional staging produces a clean, auditable commit history.
_USE _
git add CONTRIBUTORS.md
git status
-
to confirm what is staged
- Commit with Conventional Commits Format -Records a permanent, labelled snapshot of your staged changes in the repository's history.
USE
git commit -m "docs(contributors): add @yourname - Project name"
git log --oneline -3
- to verify your commits
STEP 8
Push & Open a Pull Request
- Push Your Feature Branch to Your Fork - Uploads your local branch to your fork on GitHub. A local commit can be lost; a pushed commit is durable and shareable.
USE
git push -u origin feature/yourname-add-contributor
- Open the Pull Request on GitHub- Formally proposes your branch for review and merge into the original repository's main branch.
USE
-After pushing, GitHub prints a URL — click it, or navigate to:
https://github.com/raphgm/pinpointpro/compare
-Configure the PR -head repository: YOUR_USERNAME/pinpointpro | compare: your-branch-name
-Write a clear PR title matching your commit message format. Example -docs(contributors): add @yourname - Phase 2 Project
-In the PR description, explain:
- What you changed
- Why it improves the project
-
How you tested it (if applicable)
-Click 'Create pull request'- Confirm Your PR Is Open and Awaiting Review - Always verify the end state of every action. A PR that was never submitted cannot be reviewed or merged. -Your PR should show: 'Open — 1 review required
STEP 9
- Create the README File - README.md documents what this project is and how to reproduce it — the first thing anyone sees when they open the repo.
USE
touch README.md
- Document What You Did -A good README captures what was learned and which commands prove it, so it doubles as both documentation and a portfolio artifact.
USE
printf '# PinpointPro Git Flow Contribution\n\nForked, cloned, and contributed to a real open-source repo using the full Git Flow lifecycle.\n\n## Commands Covered\n\n```
bash\ngit clone https://github.com/YOUR_USERNAME/pinpointpro.git\ngit remote add upstream https://github.com/raphgm/pinpointpro.git\ngit fetch upstream\ngit checkout -b feature/yourname-add-contributor\ngit add CONTRIBUTORS.md\ngit commit -m "docs(contributors): add @yourname"\ngit push -u origin feature/yourname-add-contributor\n
```\n' >> README.md
- Check Status and Stage Your Changes -Always check git status before committing so you know exactly what you're about to save
USE
git status
git add .
- Commit Your Work
USE
git commit -m "docs: add README for PinpointPro Git Flow lab"
- Push to GitHub
USE
git push -u origin feature/yourname-add-contributor
🎉 You Just Beat the "Git Scares"!
Look at that: you forked, cloned, branched, committed, pushed, and officially submitted a Pull Request to an open-source project.
The hardest step in open source is rarely writing the code—it’s getting past the fear of hitting Enter in the terminal for the very first time. You’ve now mastered the exact Git lifecycle used by professional engineering teams every single day.
💬 Share Your Win!
Drop your GitHub handle or your PR link in the comments below so we can celebrate your first contribution together!
Hit any roadblocks or get an unexpected terminal message? Comment with what went wrong—I'm actively checking the comments to help troubleshoot.
If this guide made Git feel a little less intimidating, don't forget to heart ❤️ and bookmark 🦄 the post so other beginners can find it.
Stay tuned for Part 2, where we'll dive into finding "Good First Issues," reading project issue trackers, and resolving your very first merge conflict!
Top comments (1)
This is brilliant and well details in steps. Welldone ify