Fork to Pull Request: The FOSS Contribution Workflow

Contributing to open source for the first time isn't hard — but the workflow has enough small gotchas that most people stumble before they get their first PR merged. This is the guide I wish existed: the full process, in order, with the parts that actually trip people up.

Before You Touch Any Code

Read CONTRIBUTING.md first. Every project has its own conventions — branch naming, commit message format, PR size expectations. Skip this and you'll waste your time and the maintainer's.

Open or find an issue before doing anything else. For anything beyond a trivial typo fix, describe what you want to change and wait for a response. This confirms the change is wanted and gives you something to reference in your PR. Spending an hour on a docs fix only to be told the section is being rewritten is avoidable.

The Workflow, Step by Step

1. Fork the repo on GitHub.
This creates your own copy under your account. You'll work here, not on the upstream repo directly.

2. Clone your fork locally.
If the folder name would clash with something you already have, rename it at clone time:

git clone https://github.com/YOUR_USER/project.git project-contrib

3. Set up your remotes.
By default, origin points to your fork. Add upstream so you can pull in future changes from the main repo:

git remote add upstream https://github.com/ORIGINAL_ORG/project.git
git remote -v

4. Create a branch for your change.
Never work directly on main (or whatever the default branch is — check first):

git checkout -b docs/fix-readme-typo

5. Make your edit and commit with a conventional message.

git add README.md
git commit -m "docs: fix typo in installation section"

Common prefixes: docs: fix: feat: chore:

6. Push your branch to your fork.

git push origin docs/fix-readme-typo

7. Open a pull request on GitHub.
Reference your issue in the description: Fixes #42. Keep the description factual and concise — what changed and why.

The Gotchas

Markdown checkbox format. GitHub task lists use - [x] not - [x ]. A trailing space breaks the rendering. Small thing, but it makes a PR look careless.

Conventional commits matter more than you'd think. Many projects use them to auto-generate changelogs. A message like docs: correct misleading flag description is useful. fix stuff is not.

Watch for abandoned forks with the same name. Popular projects sometimes have archived or dead forks that show up in search results. Always check recent commit activity before deciding where to contribute — a PR to an abandoned repo goes nowhere.

Don't use AI-generated text in PR descriptions or commit messages. Even if you used AI to understand the codebase, write your own descriptions. Maintainers can usually tell, and it signals that you didn't really engage with the change.

Why Documentation Is the Right Place to Start

You don't need to be a core developer to make a meaningful contribution. Documentation — README gaps, unclear config examples, outdated instructions — is genuinely valuable work, and it's where most contributors should start.

The best part: you already know what's wrong with the docs. You were confused by them when you were getting started. That's your contribution.

GitHub's issue search makes it easy to find these opportunities:

Good first documentation issues (general):
https://github.com/search?q=label%3A%22good+first+issue%22+label%3Adocumentation

Filtered for Linux-related projects:
https://github.com/search?q=label%3A%22good+first+issue%22+label%3Adocumentation+linux

Start with a project you actually use. The workflow above handles the rest.

Ben Santora - April 2026