mika's open learning notebook

Contributing to an established open-source project is different from building my own app because I am entering a system with existing architecture, conventions, maintainers, users, and history.

The goal is not just to make code that works. The goal is to make a change that fits the project.

Learn the repository before changing it

Before editing code, I should locate:

• contribution guidelines
• setup instructions
• test commands
• formatting/linting rules
• relevant modules
• existing issues and pull requests
• similar code paths

Reading the surrounding code is part of the implementation work.

Reproduce the problem first

For a bug fix, the strongest starting point is:

reported behavior
→ reproduce locally
→ identify minimal trigger
→ understand expected behavior
→ then change code

If I cannot reproduce or explain the problem, I have much weaker evidence that my patch fixes the right thing.

Fork, origin, and upstream

A common contribution setup is:

upstream = original project repository
origin   = my fork
local    = my clone on my machine

That distinction matters because I normally push contribution branches to my own fork while syncing changes from the original project.

A useful mental model is:

upstream/main
    ↓ sync
local main
    ↓ branch
local fix/small-bug
    ↓ push
origin/fix/small-bug
    ↓ pull request
upstream project

Keep local main boring

My local main should track the upstream project closely rather than becoming a place for experimental work.

A focused branch is easier to review, update, and throw away if the approach is wrong.

One branch, one purpose

Good contribution branches are narrow:

fix/widget-focus-regression
fix/missing-cleanup
 docs/clarify-linux-setup

A branch should avoid unrelated cleanup unless the project specifically wants it.

Small diffs are easier to understand and safer to merge.

Check whether someone already owns the work

Before starting an issue, I should check:

• is someone assigned?
• is there already an open PR?
• did a maintainer ask someone to work on it?
• does the project require an issue comment before implementation?

Open source is collaborative. Avoiding duplicate work is part of respecting other contributors.

Add a regression test when possible

A strong bug fix often looks like:

write/reproduce failing test
→ confirm it fails for the right reason
→ make the smallest fix
→ confirm the test passes
→ run related/full test suite

A regression test preserves the lesson after the patch is merged.

Review my own diff before asking others to

Before opening a PR, I should inspect the change as if I were the maintainer.

Useful checks include:

git status
git diff
git diff --check

Questions to ask:

• did I accidentally change unrelated files?
• is the patch larger than necessary?
• are comments explaining why rather than narrating obvious code?
• did debugging output get left behind?
• does the new test actually protect the behavior?

Maintainer review is part of the learning

Requested changes are not automatically a sign that the contribution failed.

Review can expose:

• project conventions I did not know
• architecture constraints
• edge cases
• compatibility requirements
• simpler solutions

The goal is to understand the reason for feedback, not just mechanically apply edits.

AI assistance does not replace ownership

AI can help me:

• navigate unfamiliar code
• explain APIs
• propose tests
• compare approaches
• spot likely failure paths

But I still need to be able to explain:

• what changed
• why it changed
• why the test proves the fix
• what tradeoffs exist
• what I would inspect if the patch failed

If I cannot explain the patch, I do not fully own it yet.

Established projects are great classrooms

Working on code written by experienced developers teaches things my own projects cannot always teach quickly:

• naming conventions
• compatibility discipline
• API stability
• review culture
• tests as documentation
• maintenance tradeoffs

BeeWare/Toga is one useful practice target because it exposes me to a real Python GUI project with an existing contributor workflow rather than only code I designed myself.

Main lesson

A good open-source contribution is focused, reproducible, tested, explainable, and respectful of the project that already exists. The work starts before the edit and continues through review.