GitHub & Portfolio

Your GitHub profile is your portfolio whether you intend it to be or not. Hiring managers will look at it. They will not look at your contribution graph or count your green squares. They will click on your pinned repositories, read your READMEs, glance at your code, and form an opinion in under two minutes. A polished GitHub with 3 strong projects beats a cluttered one with 50 abandoned repos.

What Hiring Managers Actually Look At

There is a persistent myth that hiring managers care about daily commit streaks or total contribution counts. They do not. Here is what they actually evaluate, in order:

1. Pinned repositories (the first thing visible on your profile)
2. README quality (can they understand what the project does in 30 seconds?)
3. Code quality in one or two files (do you write clean, readable code?)
4. Project complexity (is this a real project or a tutorial copy-paste?)
5. Recent activity (are you actively building, or is everything from 2019?)

What they do not care about:

- Green squares (contribution frequency graph)
- Total number of repositories
- Star counts (unless genuinely impressive, 500+)
- Forked repos with no modifications
- Tutorial projects (todo apps, calculator apps, weather apps)

Pinned Repositories

You get six pinned repos on GitHub. These are your storefront. Treat them accordingly.

Choose pins that demonstrate:

Depth over breadth: One well-built project is worth more than five surface-level ones. A fully featured CLI tool with tests, CI, and documentation shows more skill than five "Hello World" variations in different languages.
Real problems solved: Projects that solve a problem you actually had are more compelling than projects built for the sake of building. "I built this because I needed X and nothing existed" is a strong narrative.
Technologies relevant to your target role: If you are applying for backend positions, pin backend projects. If you are applying for full-stack roles, pin projects that show both.

Strong pin choices:
  - A CLI tool or library that others use (even a small audience)
  - A side project with real users or real data
  - An open source contribution you are proud of
  - A system design implementation (rate limiter, cache, message queue)
  - A data pipeline or infrastructure tool

Weak pin choices:
  - Forked repos with no meaningful changes
  - Course assignments or bootcamp projects
  - "Awesome" lists you copied
  - Repos with no README
  - Abandoned projects with 2 commits from 3 years ago

Writing Good READMEs

The README is the most important file in any repository. Most hiring managers will not clone your repo and run it. They will read the README and maybe click into one or two source files. Your README needs to answer five questions:

1. What does this project do? (one paragraph)
2. Why does it exist? (what problem does it solve)
3. How do you use it? (installation, basic usage)
4. How is it built? (architecture, key technical decisions)
5. What is the current status? (active, maintained, experimental)

A README template that works:

# Project Name

One-sentence description of what this does.

## Overview

A paragraph explaining the problem this solves and why existing
solutions were insufficient. This is where you demonstrate that
you think about problems, not just write code.

## Usage

Installation and basic usage instructions. Code examples showing
the most common use case.

## Architecture

Brief description of how the system is structured. Key technical
decisions and why you made them. This section is what separates
a portfolio project from a homework assignment.

## Development

How to set up the development environment, run tests, and
contribute.

## Status

Whether this is actively maintained, experimental, or archived.

Do not include badges for every possible tool (build status, coverage, license, code style, downloads). One or two relevant badges are fine. A wall of 15 badges looks like overcompensation.

Demonstrating Depth, Not Breadth

The single biggest mistake engineers make with their GitHub is showing breadth instead of depth. Having repos in 10 different languages and 15 different frameworks signals "jack of all trades, master of none."

Instead, go deep on one or two projects:

Shallow project (low signal):
  - Todo app in React
  - 200 lines of code
  - No tests
  - Default Create React App structure
  - README says "A todo app built with React"

Deep project (high signal):
  - Task management CLI with priority queues and recurring tasks
  - 2,000+ lines of well-structured code
  - Test suite with 80%+ coverage
  - CI pipeline that runs tests on every push
  - README explains architecture decisions
  - Handles edge cases (timezone differences, concurrent access)
  - Versioned releases with changelogs

The deep project tells the hiring manager: this person ships real software, thinks about edge cases, writes tests, and cares about code quality. The shallow project tells them nothing.

Side Projects That Stand Out

The best side projects share common traits:

They solve a real problem: "I built this because I was frustrated with X" is more compelling than "I built this to learn Y."
They have users (even a few): If anyone besides you uses your tool, mention it. "Used by 3 teams at my company" or "50 weekly downloads on npm" is real validation.
They show technical judgment: Choosing the right tool for the job, making explicit tradeoffs, and documenting why you made those choices.
They are finished: A completed project with limited scope beats an ambitious project that is 20% done. Scope down ruthlessly and ship.

Project ideas that demonstrate real engineering:
  - A rate limiter library with multiple algorithms (token bucket,
    sliding window) and benchmarks comparing them
  - A log aggregator that tails multiple files and sends to a
    central store with configurable filtering
  - A database migration tool that supports rollbacks
  - A load testing tool that generates realistic traffic patterns
  - A CLI for a service you use (wrapping an API with good UX)

Open Source Contributions

Contributing to open source is one of the strongest signals on a GitHub profile, because it demonstrates that you can:

Read and understand someone else's codebase
Follow contribution guidelines and coding standards
Communicate effectively in pull requests and issues
Write code that passes review by experienced maintainers

You do not need to contribute to Linux or Kubernetes. Smaller, focused contributions to projects you actually use are more impressive than drive-by typo fixes on famous repos.

Strong contributions:
  - Bug fix with a test case that reproduces the issue
  - Feature implementation that was requested in an issue
  - Performance improvement with benchmarks
  - Documentation improvement for something that confused you

Weak contributions (still better than nothing):
  - Typo fixes (fine as a starting point, not as a portfolio piece)
  - README formatting changes
  - Adding yourself to a contributors list

When listing open source contributions on your resume or profile, link to the specific PR, not the repo. Let the hiring manager see the actual code and discussion.

Profile Hygiene

Your GitHub profile page matters. Take 30 minutes to clean it up:

Profile checklist:
  [ ] Profile photo (professional, but it can be casual)
  [ ] Bio (one line: "Backend engineer. Building X at Y.")
  [ ] Location (helps recruiters filter)
  [ ] 3-6 pinned repos, all with good READMEs
  [ ] Archive or make private any repos that are embarrassing
  [ ] Remove forked repos you never modified
  [ ] Ensure pinned repos have recent activity (at least this year)

A clean profile with 10 repos is better than a cluttered one with 80. Do not be afraid to archive or delete old work that does not represent your current skill level.

Beyond GitHub

GitHub is the default, but it is not the only option:

Personal website: A simple site with your projects, writing, and contact info. Does not need to be fancy. A clean single-page site built with basic HTML is fine.
Technical blog: Writing about what you build demonstrates communication skills, depth of understanding, and genuine interest. Even 3-4 well-written posts can be a differentiator.
Live demos: If your project has a UI, deploy it somewhere (Vercel, Fly.io, Railway). A live demo is 10x more compelling than a screenshot.
Video walkthroughs: A 5-minute video explaining your project's architecture and demonstrating it working shows communication skills that code alone cannot.

Common Pitfalls

Green square obsession: Making trivial commits to maintain a streak adds no value and experienced engineers see through it immediately.
Tutorial-driven portfolio: Having only projects that follow tutorials (todo apps, blog engines, e-commerce clones) signals that you can follow instructions but cannot solve novel problems.
No README: A repo without a README is invisible. Even a great project is worthless if nobody can understand what it does in 30 seconds.
Breadth over depth: Twenty repos in twenty technologies is less impressive than three repos that demonstrate deep expertise. Go deep.
Outdated pinned repos: If your pinned repos have not been touched in 2+ years, they signal disengagement. Either update them or replace them with something recent.
Code quality mismatch: If your resume says "senior engineer" but your GitHub code has no tests, no error handling, and single-letter variable names, it creates doubt. Your public code should reflect the quality you claim.
Ignoring commit messages: Hiring managers occasionally look at commit history. "fix" and "update" repeated 30 times signals sloppy habits. Write descriptive commit messages, especially on portfolio projects.

Key Takeaways

Your pinned repos and their READMEs are 90% of what hiring managers see. Invest your time there, not on contribution streaks.
Depth beats breadth. Three polished projects with tests, documentation, and real-world use cases are worth more than fifty shallow repos.
A good README answers: what does it do, why does it exist, how do you use it, and how is it built. If your README does not answer these in 30 seconds, rewrite it.
Open source contributions demonstrate collaboration skills that side projects alone cannot. Even small contributions to projects you use are valuable.
Clean up your profile. Archive old repos, remove unmodified forks, and ensure your pinned projects represent your current skill level.