Introduction
Collaborating on GitHub shouldn’t feel like chaos. When everyone follows a simple flow, the team moves faster and fewer things break. Below is a pragmatic, no-fluff guide you can use today commands, explanations, and actions to take at each step.
Quick idea
Work on main? No.
Work on feature/*? Yes.
Make small commits. Open PRs. Get reviews. Merge when CI passes. Celebrate.
1) Get the repo (join the team)
Clone the official repo:
git clone https://github.com/<org>/<repo>.git
cd repo
Action: read README.md and CONTRIBUTING.md before you do anything.
2) Always start fresh (pull main)
Before you begin a task:
git checkout main
git pull origin main
Action: never start a feature on an out-of-date main.
3) Create a branch (your side quest)
Use clear names:
git checkout -b feature/auth-login
# or
git checkout -b fix/login-typo
Naming convention: feature/, fix/, chore/, hotfix/.
Action: one task = one branch. Keep branches focused and small.
4) Code and commit (small, meaningful checkpoints)
Make frequent, atomic commits:
git add .
git commit -m "feat(auth): add login endpoint with JWT"
Commit message pattern (recommended):
<type>(<scope>): <short summary>
(optional longer description)
Types: feat, fix, chore, docs, refactor, test.
Action: commit often; message clearly.
5) Keep your branch up-to-date
Option A merge main into your branch:
git fetch origin
git merge origin/main
# resolve conflicts if any, then:
git add .
git commit
Option B — rebase (advanced; don’t rebase public/shared branches):
git fetch origin
git rebase origin/main
# resolve conflicts, then:
git rebase --continue
git push --force-with-lease
Action: pick one strategy your team agrees on. Rebase rewrites history; merge keeps history linear with merge commits.
6) Push your branch to GitHub
git push origin feature/auth-login
Action: push early and often so others can see work-in-progress.
7) Open a Pull Request (PR)
On GitHub: Compare & create PR
Good PR contains:
Clear title: feat(auth): add login endpoint
What you built (short)
Why you built it
How to test locally (commands)
Screenshots or recordings if UI changes
Link to related issue/task
Action: make the PR description a mini-doc so reviewers don’t guess.
8) PR etiquette & reviews
Assign 1–2 reviewers and request a review.
Keep PRs small — easier to review, faster to merge.
When you get feedback: respond, commit fixes to the same branch, push updates.
If reviewers leave suggestions, prefer suggestion commits or explain your choice if you disagree.
Action: be courteous and specific in code reviews. Use comments as teaching moments.
9) CI checks & gating
Common rules before merge:
All CI tests pass (unit/integration/lint)
No new console logs or debug artifacts
Code coverage / quality gates met (if configured)
Approved reviews reached
Action: don’t merge if CI fails — fix it or ask for help.
10) Merge strategy (squash, merge, or rebase)
Typical options:
Squash and merge — one clean commit in main
Create a merge commit — keeps branch history
Rebase and merge — linear history
Action: follow your team’s policy. Squash is great for tidy main.
11) After merge — house cleaning
On GitHub: delete branch (optional, recommended). Locally:
git checkout main
git pull origin main
git branch -d feature/auth-login
git fetch -p # prune deleted remote branches
Action: clean branches to avoid clutter.
12) Resolving conflict- practical steps
If merge/rebase reports conflicts:
Open the files, find conflict markers <<<<<<< / ======= / >>>>>>>.
Discuss with the teammate who worked on the other change (don’t guess).
Fix, git add <file>.
Continue rebase or create a commit and push.
Commands for rebase conflicts:
# after resolving
git add <file>
git rebase --continue
# if you need to abort
git rebase --abort
Action: always talk through complex conflicts — chat saves time.
13) Pull Request checklist (copyable)
Title is clear and actionable
Description: what, why, how to test
Linked issue/task (if any)
Tests added/updated
Linted & formatted
No debug logs, secrets, or large files
CI passes
At least 1 approval
Action: add this to your PR template.
14) Short cheat sheet (commands)
git clone <repo>
git checkout -b feature/your-task
git add .
git commit -m "feat(scope): message"
git pull origin main # keep updated
git push origin feature/your-task
# on finish:
# open PR, after merge:
git checkout main
git pull origin main
git branch -d feature/your-task
git push origin --delete feature/your-task
Final action:
Before your next PR, commit to these three things:
Pull latest main.
Make one focused branch and keep it small.
Add a clear PR description + test steps.
Ship smarter, not just faster.
Goodluck!
Top comments (0)