Open Source Projects#

Day 12 · The compounding chapter

Every line of code you write at Welzin runs on a tower of other people's work. Postgres, Linux, Node, Python, React, Next.js, Qdrant, Ollama, the Anthropic SDK - the stack we ship is open source nearly all the way down. Knowing how to operate inside that ecosystem - read it, debug into it, contribute back to it - is the difference between an engineer who builds with open source and one who builds on it.

This chapter is the one with the longest tail. Treat it as a practice you start in week one and continue forever, not a course you finish.

This chapter has two halves. The first is the practice - the principles below, applicable to any project. The second (the eight sub-chapter deep-dives at the bottom) is a curated set of projects worth your time, ordered from the umbrella foundations down to specific projects. Read the practice, then pick one sub-chapter project and actually go contribute. The point of this chapter is not theory.

Outline#

1. Why open source matters at Welzin - the practical, not the ideological, case
2. Reading other people's code - the most under-rated engineering skill
3. Finding projects worth your time - and avoiding the trash
4. Your first contribution - the playbook
5. PR craft for OSS - different from internal PRs in specific ways
6. Licensing 101 - MIT, Apache, GPL, BSL, AGPL, SSPL, why it matters
7. Maintaining your own project - README, license, versioning, deprecation
8. The economics of open source - sponsorships, foundations, open core, vendor traps
9. Security, supply chain, and the long tail - what npm taught us
10. Welzin's OSS posture - what we publish, what we depend on, what we avoid

101 Primer#

Why open source matters at Welzin#

Three concrete reasons, all of them about getting your job done faster:

1. We sit on it. Postgres, Node, Next.js, React, Tailwind, Qdrant, Ollama. When a customer's bug turns out to be an upstream issue, you'll need to read the source. Sometimes you'll patch it. Sometimes you'll PR a fix.
2. We learn from it. The best examples of how to structure a Hono app, debounce a hook, write a typed HTTP client, or design a CLI all live in real OSS code - not blog posts. Read what experts actually ship, not what they recommend.
3. We publish to it. Welzin will open-source select internal tools (skills, integrations, libraries). When you write something high-leverage internally, the path-from-utility-to-released-library is short - and shipping it publicly is good for the team and the ecosystem.

There's a fourth, softer reason: contributing builds a public record of your engineering judgment. Not for ego - for trust. When a customer's CTO Googles your name, what they see should be commits and issues, not bootcamp certificates.

Reading other people's code#

The skill that compounds the most. Most engineers underrate it for years. Make it a deliberate practice.

A drill: pick a small, well-loved library you depend on (e.g., zod, commander, picocolors, nanoid). Read the entire source. It'll be smaller than you expect. Try to explain in one paragraph:

• What is the one thing this library does?
• How is the code organised - what's the entry point, where do the layers live?
• What technique is used that you'd reuse elsewhere?
• What would you push back on in code review?

Do this once a week and your taste for code calibrates rapidly.

Specifically for large projects (React, Postgres, Next.js, Kubernetes), don't read everything. Read the doc on architecture (if it exists), then read the path one specific bug or feature touches. Real understanding comes from reading code with a question in mind.

Tools that help:

• gh CLI - clone, browse PRs, search issues from the terminal.
• GitHub code search - repo:vercel/next.js path:packages/next "experimental" finds the file you want.
• Sourcegraph (or the GitHub built-in search) for cross-repo queries.
• git log -p path/to/file - see how a file evolved. Often the reason for code is in the commit that introduced it.

Finding projects worth your time#

Filter ruthlessly. Most projects are wrong for you to contribute to right now. Apply this checklist:

• Do you actively use it? Contributing to projects you don't use is busywork. You won't know what good looks like.
• Is the maintainer active? git log --since=1.month.ago should not be empty. Look at issue response time.
• Is the project well-mannered? Read 5 random merged PRs. Are reviewers kind? Are PRs welcomed? Some otherwise-great projects have toxic maintainers - avoid.
• Is there low-hanging fruit? Look for good first issue / help wanted labels. Open issues with no PR.
• Is the license OK with your goals? Some contributor agreements (CLAs) demand copyright assignment. Read before signing.

The trap to avoid: Hacktoberfest spam. Don't write a "fix typo in README" PR to clock five-contribution October badges. It wastes the maintainer's time and trains a habit of theatre over substance.

The opposite extreme also exists: people try to fix bugs in projects they've never used, because they want a famous name on their CV. The PR usually misses context, gets bounced, and embarrasses everyone. Use the project first. Hit a real friction. Then contribute.

Your first contribution - the playbook#

The 80% case for a first contribution:

1. Find a real bug or missing capability in a project you use. The friction is the signal - that's where your contribution has value.
2. Search existing issues and PRs. Don't open #4571 when #1283 is already discussing the same thing. Comment there if you have new info.
3. Open an issue first if the project doesn't have one. Describe the problem, propose a direction, ask "would a PR for this be welcome?" Save yourself a week of work the maintainer will reject as out of scope.
4. Fork. Branch. Code. Test. PR. Standard Git workflow (Chapter III).
5. Match the project's style. Run prettier / gofmt / whatever they use. Mirror their test patterns. If they require sign-off (git commit -s), do it.
6. Reference the issue in the PR description. "Closes #1283."
7. Wait. Don't bump the PR after one day. Maintainers have lives. A week is reasonable. Two weeks, polite "any updates?" comment.
8. Take feedback well. Even unfair feedback. It's a public record; act like a professional.

If the PR gets merged: ship-it. If it gets bounced: thank the reviewer, ask what would make it acceptable, decide if it's worth iterating or moving on. Both outcomes are wins for you - you've started reading and writing in someone else's codebase.

PR craft for OSS - different from internal PRs#

What changes versus the internal PR craft from Chapter III:

• More context in the description. The reviewer doesn't have your meeting history. Spell out the problem, the chosen approach, alternatives considered, and trade-offs.
• Smaller diffs win bigger. A 50-line PR with a clear test gets reviewed today. A 600-line refactor sits for a month.
• One change per PR. Mixing a bug-fix with a refactor with a rename is a guaranteed bounce. Split.
• Add tests. Most OSS projects require them. Even if not required, adding a test for your change signals you're serious.
• Update docs/README/CHANGELOG. Whatever the project's convention is. Find an analogous past PR and copy its shape.
• Be patient with maintainer requests. "Please rebase" / "Please squash" / "Please add a test for X" - just do it. Arguing the toss costs goodwill.

Licensing 101 - read this before you copy code#

You will be tempted to lift code from somewhere into the Welzin codebase. Stop and check the license.

Practical rules at Welzin:

• Default to MIT / Apache for any code we ship or depend on.
• GPL/AGPL is a careful conversation. We can use GPL'd CLI tools (we're not linking). AGPL servers as dependencies (e.g., some forks of Postgres extensions) need legal sign-off.
• Never copy-paste code from Stack Overflow without checking the license - SO's default is CC BY-SA 4.0, which has attribution requirements.
• When in doubt, ask. The cost of an email is much less than the cost of a license violation discovered in due diligence.

Maintaining your own project#

When you publish something open source - even a 200-line utility - it's now infrastructure for strangers. Treat it accordingly.

Minimum bar for a public repo:

• A clear README answering: what does this do? why does it exist? quick install / quick use. One screenshot or one code block under the fold.
• A LICENSE file - MIT or Apache 2.0 by default. Without it, the code is technically not OSS; nobody can legally use it.
• A working npm install / pip install / go get. If the install instructions don't work on a fresh machine, fix them before you advertise the repo.
• Semantic versioning. MAJOR.MINOR.PATCH. Breaking changes bump major. Always.
• A CHANGELOG. Even a Markdown file with bullets. Future-you and your users need it.
• CI running tests on every PR. GitHub Actions, ten lines (Chapter III).
• An issue template if you have any users. Reduces the time-wasted-debugging-empty-issues tax.

When you can't maintain it anymore:

• Say so. Add a notice to the README: "This project is in maintenance-only mode. PRs are welcome; new features are not on my roadmap."
• Archive the repo if you've genuinely walked away. GitHub's "Archive" button is honourable; abandoning the repo without a notice is not.
• Hand it off to a willing maintainer rather than letting it rot.

The economics of OSS#

Open source is not free - someone is paying for it, just not the user. Understand who, and what their incentives are, before you bet your stack on a project.

• Solo maintainer, weekend project - Lovely. Brittle. Plan for the maintainer to disappear.
• Foundation-backed (Linux, Apache, CNCF) - Multiple companies share burden. Generally safe long-term.
• Vendor-led (e.g., Vercel/Next.js, MongoDB Inc./MongoDB, Elastic/Elastic) - The product roadmap follows the vendor's commercial interest. Watch for license rug-pulls (MongoDB → SSPL, Elastic → SSPL, Redis → SSPL, Terraform → BSL). It can happen to anything VC-backed.
• Open-core - Free version intentionally lacks features that the paid version has. Fine, but understand which features.
• "Public-source" - Source visible, but license forbids redistribution. Not OSS. Don't treat it as such.

Supporting the maintainers of what you depend on isn't charity, it's risk management. GitHub Sponsors is fifty bucks a month and an asymmetric bet on stability.

Security and supply chain - the long tail#

The single most important thing that's changed in the last few years: package managers have become attack surfaces. event-stream, colors.js, node-ipc, xz - supply-chain attacks via popular OSS packages are now routine.

Defensive habits:

• Pin versions in lockfiles. Commit package-lock.json / poetry.lock.
• Audit dependencies. npm audit, pip-audit, osv-scanner. Wire into CI.
• Beware new typo-squatted packages. cross-env vs crossenv is the kind of mistake that costs you a node.
• Minimise dependency tree depth. Every transitive dep is a risk. Tools like npm ls, pnpm why show what's in your tree.
• Lock binary downloads. curl | bash is a supply chain attack vector. Verify checksums.
• Stay current. Quarterly dep-bump days are good practice. Older deps accumulate CVEs.

Welzin's OSS posture#

What we publish:

• Skills (Claude Code), once they've proven their worth internally.
• Bootcamp curriculum (the thing you're reading).
• Specific integrations (data connectors, transformers) we'd want our customers to be able to fork.

What we depend on:

• A short, named list of "tier-1" dependencies we'd patch and ship internally if upstream went away (Postgres, Node, Next.js, Tailwind, Anthropic SDK).
• A "tier-2" list of useful libraries we'd swap out without crying.

What we avoid:

• AGPL'd server-side dependencies, unless legal has signed off.
• Single-maintainer projects on critical paths (we vendor or fork).
• Recently-relicensed projects until the dust settles.

What we don't open source:

• Customer code. Ever.
• Anything that contains a credential, even in commit history.
• Proprietary IP that's the core of our product.

Hands-on Checkpoints#

• Pick a small OSS library you use daily (≤2k LOC). Read the source. Write a 200-word internal note: what it does, how it's organised, what you learned.
• Find a real bug or papercut in a project you use. Open a well-written issue. Don't write code yet.
• If the issue is welcomed, send a PR. Tests included. Pass CI. Take review feedback gracefully.
• Audit package.json / requirements.txt of any Welzin repo. For each top-level dep, answer: license? maintainer model? alternatives if it died? Write the answers in a 1-page doc.
• Publish a 100-line utility of your own with: README, LICENSE (MIT), tests, GitHub Actions CI, semver-compliant first release. Tag v0.1.0.
• Set up osv-scanner (or equivalent) in CI for a Welzin repo. Get it green.
• Sponsor one maintainer of a dependency you rely on. $5/month is enough. The point is the habit.

Further reading#

• Producing OSS - Karl Fogel, the canonical book. Free online.
• Open Source Guides - GitHub's official primers
• choosealicense.com - license picker that actually helps
• Securing the open source supply chain - OpenSSF resources
• Hyrum's Law - one sentence that explains a decade of OSS pain
• The Cathedral and the Bazaar - Eric Raymond, historical, still useful
• Backstage - Open source software anti-patterns - what not to do as a maintainer

Welzin opinion: Open source is not a hobby; it's the substrate. Engineers who can read upstream, fix upstream, and ship to upstream are 2× more valuable than ones who can only operate on the surface. Start contributing in your first month. Don't wait until you "feel ready" - you'll never feel ready.