Standards¶

Coding conventions, naming patterns, and architecture principles that apply across all Jersal projects. These standards ensure consistency as the number of projects grows.

Why standards matter¶

With multiple repositories sharing infrastructure and following the same template, consistency reduces cognitive load when switching between projects and makes it easier for readers to navigate any project's codebase.

Standards index¶

Standard	Scope	Description
Coding conventions	All projects	Language preferences, strict mode, formatting, and code quality
Naming conventions	All projects + infrastructure	How we name repositories, resources, files, and variables
Architecture patterns	All projects	Design principles, infrastructure patterns, and decision-making framework

Applying standards¶

New projects inherit standards through the project template, which pre-configures branch naming, commit messages, merge strategy, editor config, and the planning-first workflow
This hub is the source of truth -- the template's CONTRIBUTING.md and README.md reference these standards
Existing projects should be updated to match when feasible
Exceptions should be documented as project-level decisions in the project's docs/ folder
Changes to standards should be proposed through a PR and, if significant, recorded as an ADR

Enforcement chain¶

graph LR
    HUB["Hub Standards<br/>(source of truth)"] --> TPL["Project Template<br/>(inherits conventions)"]
    TPL --> PROJ["New Projects<br/>(created from template)"]
    TPL --> CI["CI Gates<br/>(planning-gate, rulesets)"]
    CI --> PROJ

Standards are enforced through:

Documentation -- This hub defines the canonical rules
Template -- The project template bakes conventions into .editorconfig, CONTRIBUTING.md, setup-repo.sh, and CI workflows
CI -- The planning gate blocks code until planning is approved; branch rulesets enforce squash merges and linear history
Code review -- PRs reference these standards during review