Nimesh Kulkarni

Posted on May 25

GitHub Glow-Up: Open Source, READMEs, Badges, Streaks, Git and gh CLI

#github #git #beginners #opensource

If you are trying to look more serious on GitHub, do not start with a fake-perfect profile.

Start by becoming useful.

That means learning how open source works, writing READMEs people can actually follow, using Git without panic, and using the GitHub CLI so you do not live inside browser tabs all day. Badges, streaks, profile cards, and contribution graphs help, but only after the work underneath them is real.

This is the practical version of the GitHub glow-up.

1. Pick open source projects like a normal person

A common beginner mistake is hunting for a famous repo and trying to force a contribution. That usually ends with confusion, ignored comments, or a pull request that solves a problem nobody asked you to solve.

A better way:

Pick a tool, library, template, or documentation site you already use.
Read the README first.
Check CONTRIBUTING.md, the license, issue templates, and open pull requests.
Search for labels like good first issue, help wanted, documentation, or bug.
Before touching a big change, comment on the issue and ask if the approach makes sense.

Small contributions count. Fixing unclear docs, improving examples, adding a missing test, reproducing a bug properly, or simplifying setup instructions can be more useful than a half-baked feature.

Maintainers do not owe you mentorship on demand. Their job is to protect the project. Your job is to reduce their work, not create more of it.

2. The basic open source flow

Most GitHub open source work follows the fork-and-pull model.

# Fork the repo on GitHub first, then clone your fork
git clone https://github.com/YOUR_USERNAME/PROJECT.git
cd PROJECT

# Add the original repo as upstream
git remote add upstream https://github.com/OWNER/PROJECT.git

# Create a branch for your work
git checkout -b fix-readme-setup-steps

# Make changes, then check what changed
git status
git diff

# Commit and push
git add README.md
git commit -m "Clarify local setup steps"
git push -u origin fix-readme-setup-steps

Then open a pull request from your branch into the original repo.

A good pull request explains:

what changed
why it changed
how you tested it
which issue it closes, if there is one

Example:

## What changed
Clarified the local setup instructions for Node 20 users.

## Why
The old steps skipped dependency installation and caused the dev server to fail.

## Testing
Ran `npm install` and `npm run dev` locally.

Closes #123

Do not dump unrelated improvements into one PR. A small focused PR is easier to review and much more likely to get merged.

3. Git basics you should know before contributing

Git is version control. It tracks changes, lets you work safely in branches, and gives maintainers a clean history of what happened.

The core commands are enough for most beginner contributions:

# See current changes
git status

# Create and switch to a branch
git checkout -b my-change

# Stage files
git add README.md

# Commit staged files
git commit -m "Improve README examples"

# Download latest changes from a remote
git pull

# Push your branch
git push -u origin my-change

If you are contributing to a repo you forked, keep your fork updated:

git checkout main
git pull upstream main
git push origin main

If your branch gets old, update it before asking for review again:

git checkout my-change
git merge main

You do not need to become a Git wizard on day one. But you should understand branches, commits, remotes, and pull requests. That is the minimum kit.

4. Use GitHub CLI when the browser gets annoying

GitHub CLI, or gh, brings GitHub issues, PRs, repos, releases, Actions, and API calls into your terminal.

Install it, then log in:

gh auth login
gh auth status

Useful commands:

# Clone a repo
gh repo clone owner/repo

# Fork and clone a repo
gh repo fork owner/repo --clone

# View issues
gh issue list

# View good first issues
gh issue list --label "good first issue"

# Create a PR from your current branch
gh pr create --fill

# Check PR status
gh pr status

# View CI checks
gh pr checks

# Review a PR locally
gh pr checkout 123

# Merge when you own the repo and checks are green
gh pr merge --squash

The difference between git and gh is simple:

git manages source history: branches, commits, merges, remotes.
gh talks to GitHub: issues, PRs, Actions, releases, repos, API.

Use both. They solve different problems.

5. Write a README that saves people time

A README is not decoration. It is the front door of your project.

A good README answers these questions fast:

What does this project do?
Who is it for?
How do I install it?
How do I run it locally?
How do I configure it?
How do I test it?
Can I see screenshots or a demo?
How do I contribute?
What license does it use?

A clean README structure:

# Project name

One short sentence explaining what it does.

## Demo

Live link or screenshot.

## Features

- Feature one
- Feature two
- Feature three

## Tech stack

- Next.js
- TypeScript
- PostgreSQL

## Getting started

```bash
git clone https://github.com/username/repo.git
cd repo
npm install
npm run dev
```

## Environment variables

Create `.env.local`:

```env
DATABASE_URL=
NEXT_PUBLIC_APP_URL=
```

## Tests

```bash
npm test
```

## Contributing

Read `CONTRIBUTING.md` before opening a PR.

## License

MIT

Keep it real. Do not add ten badges, five animated banners, and a wall of vague promises if the app barely runs. Screenshots, commands, and honest limitations are more useful.

6. Badges: useful, but do not turn your README into a sticker shop

Badges are those small labels at the top of many READMEs. They can show build status, package version, license, test coverage, deployment status, tech stack, or social links.

Shields.io is the easiest way to make them.

Examples:

![License](https://img.shields.io/github/license/username/repo)
![Stars](https://img.shields.io/github/stars/username/repo?style=social)
![Last commit](https://img.shields.io/github/last-commit/username/repo)
![Issues](https://img.shields.io/github/issues/username/repo)

A sensible badge set:

![Build](https://img.shields.io/github/actions/workflow/status/username/repo/ci.yml?branch=main)
![License](https://img.shields.io/github/license/username/repo)
![Last commit](https://img.shields.io/github/last-commit/username/repo)
![Open issues](https://img.shields.io/github/issues/username/repo)

Badges should tell readers something useful. Build passing? Good. License? Good. Version? Good. Random profile trophies stacked like a gaming HUD? Maybe relax.

7. Streaks and contribution graphs: maintain them honestly

GitHub streaks are fun. They are also overhyped.

A green contribution graph can show consistency, but it does not prove engineering skill. A person can make one tiny commit every day and still avoid hard work. Another person can make one excellent PR after a week of debugging and have fewer green squares.

Still, consistency helps. If you want to keep a healthy streak, do it with real work:

ship small fixes to your own projects
write tests
improve docs
review issues
clean old TODOs
update examples
contribute to open source when you have something useful to add

If commits are missing from your graph, check the boring stuff first:

git config user.name
git config user.email

The email used in your commits must be connected to your GitHub account. GitHub also has rules for which commits appear on your contribution graph, so do not panic if one commit does not show instantly.

For profile cards and streak images, many developers use generated images in their GitHub profile README, for example:

![GitHub stats](https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=tokyonight)

![GitHub streak](https://github-readme-streak-stats.herokuapp.com/?user=YOUR_USERNAME&theme=tokyonight)

Use them lightly. One stats card and one streak card is enough. Your pinned projects and actual work matter more.

8. Profile README: make it easy to understand you

If you create a public repo with the same name as your GitHub username, GitHub shows its README on your profile.

For example, if your username is octocat, create:

octocat/octocat

A good profile README can include:

# Hey, I'm Nimesh

I build web apps, AI tools, and open source projects.

## What I'm working on

- Building: project name
- Learning: topic
- Open to: internships, open source, collaboration

## Featured projects

- [Project 1](https://github.com/username/project-1): one-line description
- [Project 2](https://github.com/username/project-2): one-line description

## Writing

- [Blog post title](https://dev.to/username/post)

## Links

- Portfolio: https://example.com
- LinkedIn: https://linkedin.com/in/username
- X: https://x.com/username

Do not write like a startup landing page. Write like a developer a recruiter or maintainer can understand in 20 seconds.

9. A weekly GitHub routine that actually works

If you want GitHub to become a strength, make it boring and repeatable.

Once a week:

update one project README
close or triage old issues in your own repos
push one real improvement to a project
look for one beginner-friendly open source issue
read one merged PR in a project you admire
clean your pinned repositories
check failing GitHub Actions

This is how your profile starts looking serious without pretending.

10. The simple rule

Open source is not about collecting green squares. GitHub is not a museum for badges.

Use GitHub to show how you think, how you improve things, and how you collaborate. A clean README, focused commits, respectful pull requests, useful badges, and a steady contribution habit will do more for your profile than any fake polish.

Start small. Be useful. Keep showing up.