Engineering practices

These pages are the single source of truth for how work is done across Codrlabs Open projects. If a project’s own docs disagree with this section, this section is what we meant.

None of it was written in the abstract. Every page here is distilled from practice on a real codebase — mostly Vizably — including the parts that went wrong first. Where a rule exists, it exists because something broke without it.

What is here

Page	Answers
Layered architecture	“Which layer does this change belong in, and what must I not touch?”
Pull requests	“How do I get a change from an issue to main?”
Reviewing	“How do I review someone else’s pull request?”
Git recovery	“I’ve made a mess of this branch. How do I fix it?”
Documentation	“Where does this document go, and does it belong in a repo at all?”

The through-line

Three ideas connect all of it.

Name the layer before you edit the file. The path tells you the layer, the layer tells you the rules, and the rules tell you what you may not touch. That is the difference between building and hacking.

The best change is a small change in one place. A pull request touching three layers at once usually means two responsibilities got collapsed into one. Split it.

Write down what you had to work out. The recovery steps on these pages exist because somebody spent an afternoon on them. Nobody should spend it twice.