15 - Your First Contribution¶

What this session is¶

The whole thing. We walk through making a real contribution to a real Linux-adjacent OSS project, end to end.

By the end you'll have submitted a pull request. When it merges (days or weeks later), you'll be an open-source contributor - a small, real one.

The workflow¶

Same as every other language path:

Fork on GitHub.
Clone your fork.
Add upstream as a remote.
Branch off main.
Set up dev environment, install any required tools.
Change the file(s); test if applicable.
Run lints / tests locally (same commands as CI).
Push to your fork; open the PR.

Prerequisites: git installed and configured¶

sudo apt install git              # Linux
brew install git                  # macOS

Configure once per machine:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false

For GitHub SSH auth, you should already have a key from page 12. If not, generate one and add to GitHub (page 12 covered this).

Test:

ssh -T git@github.com

Should respond with your username. If "permission denied," your key isn't on GitHub.

Step 1: Fork¶

GitHub → Fork (top right). Creates github.com/<you>/<project>.

Step 2: Clone¶

git clone git@github.com:<you>/<project>.git
cd <project>

(Use the git@github.com: URL for SSH clone - works with your SSH key. The https:// form requires a personal access token for pushes.)

Step 3: Add upstream¶

git remote add upstream git@github.com:<owner>/<project>.git
git fetch upstream
git remote -v

You should see origin (your fork) and upstream.

Step 4: Branch¶

git checkout -b fix/typo-in-readme

Step 5: Set up the dev environment¶

Read CONTRIBUTING.md. Install any tools it mentions:

shellcheck (for shell projects): sudo apt install shellcheck.
pre-commit (some projects use it): pip install pre-commit && pre-commit install.
Tool-specific: Hugo / MkDocs for docs builds, Ansible for Ansible projects, etc.

Run their test command. Confirm green before changing anything.

Step 6: Make the change¶

Open the file in your editor. Make the change. Save.

Keep it small, focused, conventional:

A docs PR fixing a typo: one line changed.
A dotfiles PR adding an alias: one line added.
A tldr-pages PR fixing an example: one or two lines changed.
A shell-script PR improving error handling: a small block.

Step 7: Run lints / tests locally¶

For shell projects:

shellcheck path/to/script.sh

For tldr-pages (which has its own linter):

# they have a Markdown linter; the CONTRIBUTING tells you
npm install
npm run test       # or similar

For docs sites (e.g., MkDocs):

mkdocs serve       # builds locally; serves at localhost:8000

If anything fails, fix locally. Don't push red.

Step 8: Commit and push¶

git add <files>
git commit -m "docs: fix typo in installation section"

Commit message conventions vary by project. tldr-pages, for example, expects: <page>: <action> like git checkout: add new example.

Push:

git push origin fix/typo-in-readme

GitHub prints a URL - click it to open the PR page.

Step 9: Open the PR¶

On the upstream repo, you'll see "Compare & pull request" banner.

Title. Short, descriptive.
Description. What changed and why. Reference the issue: Closes #123.
Checklist. Address every item in the PR template.

Submit. CI runs. Wait. Fix anything red by pushing more commits.

What happens next: review¶

Same as any OSS project:

"LGTM, merging." Done.
"Could you change these?" Most common. Address comments.
"Not what we want, but thanks." Rare for good-first-issue work.
Silence. Polite check-in after 1 week.

For tldr-pages and similar high-volume welcoming projects, PRs often merge within a day.

After the merge¶

Update your fork's main:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Delete the branch.
Take a screenshot.

Worked example: a tldr-pages fix¶

Suppose you noticed tldr ls doesn't have an example for ls -lh /path. You decide to add one.

git clone git@github.com:<you>/tldr.git
cd tldr
git remote add upstream git@github.com:tldr-pages/tldr.git
git fetch upstream

git checkout -b ls-add-human-readable-example

# Edit pages/common/ls.md, add an example
nano pages/common/ls.md

Add a section like:

- List in long format with human-readable file sizes:

`ls {{[-lh|--long --human-readable]}} {{path/to/directory}}`

Save. Test (read the CONTRIBUTING for tldr-pages's linter):

npm install                # one-time
npm run test                # or: just the linter they mention

If green:

git add pages/common/ls.md
git commit -m "ls: add human-readable size example"
git push origin ls-add-human-readable-example

Open the PR. Address review (often "please reword to match our style guide"). Merged.

You're now a tldr-pages contributor.

After your first PR: what next¶

Pick another issue in the same project. Each PR is faster than the last.
After 3-5 PRs, become a regular. Review others' PRs (you don't need to be a maintainer to leave helpful comments).
Build your own dotfiles / scripts repo. Use git for version control. Publish on GitHub.
Pick a programming language. This path got you to "I can contribute config and docs." Pick up Go, Python, or Rust to contribute code.

Recommended next paths on this site:

Programming language paths: Go from scratch, Python from scratch, Rust from scratch. Pick the one whose ecosystem interests you most.
Linux Kernel - the deep path. Assumes you can program in C and have used Linux comfortably. You've done the second.
Container Internals + Kubernetes - Linux runs the cloud. These paths cover how.

What you might wonder¶

"My PR sat for weeks?" Polite check-in. Some projects are slow; some abandoned. Pick another.

"Maintainer was rude?" Disengage. Try another project.

"I'm not actually programming. Does this count as 'real' OSS contribution?" Yes. Docs and configs are as load-bearing as code. Maintainers value docs PRs heavily - they fix them less themselves.

"What about contributing to the Linux kernel itself?" Different path, requires C + deep Unix knowledge. The "Linux Kernel" path on this site is the on-ramp.

Done with this path¶

You've: - Installed Linux/WSL/macOS terminal access. - Navigated the filesystem confidently. - Managed files, permissions, processes. - Written shell scripts. - Used package managers and networking tools. - Read a real Linux-adjacent OSS project. - Picked, prepared, and submitted a PR.

What you should not do: claim you "know Linux" now. You know enough to use it daily and contribute small fixes. There's much more - the kernel, the deep parts of /proc and /sys, performance work, security hardening, distributed systems on Linux.

What you should do: keep using the terminal. Daily. Even when it's slower than a GUI. Familiarity compounds; in a year you'll do many things faster in the terminal than you ever could in a GUI.

Congratulations. You are no longer a beginner.