Learning to Contribute to FOSS Projects

Ben Santora — Sat, 11 Apr 2026 09:53:18 +0000

Contributing to the open source community is more important than ever in 2026. It isn’t particularly difficult, but like so much of the git ecosystem, the workflow isn't intuitive and there are a few pitfalls that can trip you up. This guide outlines a typical example of the complete process.

Read CONTRIBUTING.md first. Every project has its own conventions — branch naming, commit message format, PR size expectations. Don't skip this.

For your first few contributions, rather than opening an issue — find one. Browse the project's issues tab, filter by good first issue or documentation, and pick something small that's already been validated as needed. Once you're more familiar with the process, you can contribute to projects you actually use - then you can start identifying and opening your own issues. If your aim is to learn the process, keep the first fix simple.

The Workflow

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.
Clone it into whatever directory you want to work from — this is where all your local editing will happen.

git clone https://github.com/YOUR_USER/fossproject.git

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

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

This gives you two remotes: origin (your fork, where you push) and upstream (the real project, where you pull from). You never push to upstream directly.

4. Create a branch for your change.
A branch is an isolated workspace for your change. Think of it as a copy of the project files that's separate from the main codebase — you make your edits there without touching anything else. When you're done, the branch is what gets submitted as your PR. Create a fresh one for every contribution.

First, check what branches exist and which is the base branch:

git branch

The active one has an asterisk next to it. Not all projects use main as their base branch — in my most recent contribution to anomalyco/opencode, dev was used instead. Always check before you start. Get onto that branch, sync it with upstream, then create your new workspace:

git checkout dev
git pull upstream dev
git checkout -b fix/issue-18953

Never work directly on the base branch. Each contribution gets its own fresh branch.

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.

Some pitfalls

Markdown checkbox format. GitHub task lists use - [x] not - [x ]. This happened to me recently, while inserting the 'x' in the brackets, a trailing space was created - and that breaks the rendering. Small thing, but it displayed a 'needs compliance' warning with plans to auto-close the PR until I found it and fixed it.

Format your commit messages properly. Many projects use scripts that read commit messages to automatically build changelogs. A message like 'docs: correct misleading flag' description gets categorized and included correctly. 'fix issue' is likely to get skipped or produces a useless entry.

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 analyze and understand the codebase, write your own description. Maintainers can usually spot AI-generated text and while it will probably not get rejected, it signals that you didn't really engage with the change.

Remember, you don't need to be a 10x developer to make a meaningful contribution. I'm a technician, not a software dev - my coding skills are limited, but I'm competent at reading and writing documentation. So that's what I tend to contribute — README gaps, unclear config examples, outdated instructions. etc.. Working on documentation is genuinely valuable work, and welcomed by most projects - developers are often too busy with the code to focus on documentation. But once you learn to navigate the process of contributing, you can contribute with whatever skills are your strengths.

If you're not sure where to begin, just search. GitHub's issue search makes it easy to find opportunities:

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

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

It's satisfying to start with a project you actually use and want to support. But if that's a large and complex project, start with something smaller - many solo developers welcome help and will post issues too.

Let's be honest, we all use open source software daily - it's only fair to give back a little. It's also satisfying and interestingly enough, stress-free - because you can choose what you want to work on, where and when. With every passing day, hyperscalers and large proprietary AI and software companies gain more and more control over the world's hardware and software. FOSS needs our encouragement and support more than ever.

Ben Santora - April 2026

Two Excellent Open-Source AI Agents for Your Terminal

Ben Santora — Fri, 10 Apr 2026 19:26:03 +0000

In the fast-moving world of AI-assisted development, the spotlight often shines on the models themselves, but it's the frameworks around them — the ones that integrate, manage, and streamline workflows — that define the user's experience and workflow.

The open-source contributions to CLI agents are largely eclipsed by the proprietary versions - Claude Code, CoPilot, Codex, Cursor etc.. But there are two standout FOSS terminal-based agents I've used that I feel deserve more attention: Crush from the Charmbracelet team and OpenCode from Anomalyco (formerly SST). Interestingly, both evolved from the same early Go-based project before splitting directions in 2025.

Charmbracelet carried forward the Go tradition with Crush, building both the frontend and backend entirely in Go. Powered by Charm’s elegant libraries like Bubble Tea, Crush delivers a very polished terminal-native experience — no JavaScript, no TypeScript, just clean Go engineering and minimal dependencies.

The Anomalyco team took the opposite path with OpenCode, rewriting the project in TypeScript and embracing a cloud-native, client/server architecture. Drawing on SST’s serverless expertise, OpenCode integrates with over 75 model providers, supports LSP, desktop apps, and scales across millions of monthly users.

Charmbracelet’s world is small but passionate — around 15.000 followers, 90+ contributors, and 23K stars. Crush speaks to developers who value terminal craftsmanship and design precision.

Anomalyco runs at enterprise scale. OpenCode currently shows over 140K stars, 800+ contributors, and 11,000 commits, serving over 6 million developers each month. Its rapid iteration and vast reach come from deep roots in cloud-native tooling.

These frameworks prove that the experience of running the large language models is just as vital as the models themselves. While Crush offers simplicity and beauty grounded in Go, OpenCode amplifies reach and flexibility through its modern TypeScript architecture.

Together, they reinforce how open-source diversity powers developer freedom. In a landscape increasingly dominated by proprietary AI platforms, tools like Crush and OpenCode ensure innovation, transparency, and community-driven growth. With AI in particular, keeping FOSS competitive and in the race is important.

So, a gentle nudge . . .

If you’ve ever benefited from open-source software — and we all have — consider giving back. Star a project, fix a bug, write or edit documentation, or just share your experiences with these FOSS tools. Every small act keeps the open web alive and thriving.

Ben Santora - April 2026

Forem: Ben Santora

Learning to Contribute to FOSS Projects

The Workflow

Some pitfalls

Two Excellent Open-Source AI Agents for Your Terminal