Contributing

• Bug fixes on a fix/… branch; features on a feat/… branch. Merge to main only after the gate is green — and remember that merging to main publishes a release when the branch carries a feat or a fix.
• Main is protected. Force-pushing to it and deleting it are both blocked. Neither is something anyone needs, and both are things that cannot be undone by the person who did them.
• Commit after each self-contained step, not once at the end of a body of work. A commit that does one thing can be read, reverted and bisected; one that does six cannot.
• Read Scope and principles first. A change outside it is a conversation to have before the code, not in a pull request.

Conventional prefixes — feat, fix, docs, refactor, with a scope where it helps (fix(tv):).

The body should say why, and specifically what was wrong before. A message reading "fixed the settings screen" is worth nothing six months later; one that says the gear had no click handler and could not be reached because the focus search walks past a descendant of the focused node is worth reading twice.

Record what you did not do, too. A commit that fixes three of four reported problems should say which one it left and why.

Three tests a change is held to, all of them learned the hard way:

1. Can you reach it from a running app, and does changing it change what you see? If not, it is not a feature. See the audit.
2. What does it cost the user's provider? Any new per-item network call must answer what renders the result and what happens when a list is flung or a D-pad is held.
3. Does the comment say why, or what? The code says what. Comments in this project are for the reasoning that would otherwise be lost — particularly for anything that looks removable and is not.

Quiblo is built by a small team — Mahmoud and Claude — working together on the same codebase. Several of the practices above are shaped by where that pairing goes wrong, and two are worth stating outright.

A plausible diagnosis is not a diagnosis. The catalogue shake went through four confident, wrong explanations before the right one. The first was that a list row grows when its guide arrives; the arithmetic disproved it, because a fixed-size logo dominates the row and its height cannot change. Each fix was reverted rather than shipped. A fix built on a wrong story is worse than no fix, because it looks like the question is closed.

What broke the deadlock was a detail from the person holding the remote — that the first row never shook — which none of the four explanations accounted for and the real one turns entirely on. An observation that your theory cannot explain is worth more than the theory.

The fifth attempt was measured rather than argued: a harness that reads the list's position off every frame, showing the fault before and its absence after. The whole diagnosis is written up, because the mechanism is more instructive than the fix, which is two modifiers in the other order.

Say what was not verified. Several things in this project were confirmed on an emulator and are recorded as exactly that, not as passing. The gap between "the code does this" and "I watched it do this" is where the interesting bugs live.