Conventions for contributing to Banjo.
Where to file things
Conventions
| What | Convention | Example |
| Design decisions | MADR 4 records in docs/design/ | docs/design/0002-use-c99-for-the-library.md |
| Branching model | Trunk-Based Development | main, release/1.2 |
| Branch names | Conventional Branch 1.1.0 | feat/maze-radial-example |
| Commit messages | Conventional Commits 1.0.0 | fix(audio): check pthread_create return (#149) |
| Changelog | Keep a Changelog 1.1.0 | - Wilson's generation algorithm |
| Version numbers | Semantic Versioning 2.0.0 | 1.2.0-rc.1 |
| Release tags | v + version | v1.2.0 |
| Header files | Standalone headers, fixed include order | #include <banjo/api.h> |
| Doc comments | Doxygen, backslash directives | \brief |
| Behavior specs | docs/spec/, cases in test/spec_<domain>.c | docs/spec/rect-001-rectangles.md |
| Backlog | Versioned as files under the backlog folder | |
Versioning
Banjo uses Semantic Versioning (SemVer). A version number looks like MAJOR.MINOR.PATCH:
- MAJOR: incremented when changes break backward compatibility (existing code using Banjo may need modifications).
- MINOR: incremented when new features are added in a backward-compatible way (existing code continues to work, new capabilities available).
- PATCH: incremented for backward-compatible bug fixes only.
Before a stable release, versions go through pre-release stages:
| Stage | Meaning |
| alpha | Development version. New features expected. Stable only by CI/CD. |
| beta | More mature. Can still add new features. |
| preview | Feature freeze. Bug fixes only. |
| rc | Release candidate. Only critical fixes. |
| (none) | Stable release. |
Pre-release versions look like 1.2.0-alpha, 1.2.0-beta, 1.2.0-preview, 1.2.0-rc. When multiple iterations are needed, they can be numbered: 1.2.0-rc.1, 1.2.0-rc.2.
The version is defined in inc/banjo/version.h: this is the single source of truth.
Stable releases are tagged vX.Y.Z (e.g. v1.2.0). Pre-release stages are tracked in version.h, not by branches, and a pre-release gets a tag only when it is published on the Releases page, with its full version (e.g. v1.2.0-rc.1). A tag always matches version.h at the commit it names, and the release workflow refuses one that does not.
Branching model
Banjo uses Trunk-Based Development, a simple branching model where all development flows through a single main branch.
| Branch | Purpose | Version |
| main | Active development. Always deployable. | X.Y.0-alpha |
| release/X.Y | Stabilization and maintenance of version X.Y | X.Y.0-alpha → beta → preview → rc → X.Y.0 |
These are the only long-lived branches. Every other branch is short-lived and is deleted once its pull request is merged.
The main branch is the trunk. It always contains the latest development code, always passes CI, and is always at an -alpha version. All new work lands here first.
Release branches (release/X.Y) are created when it's time to stabilize a version. Once a release branch is cut:
- The release branch progresses through alpha → beta → preview → rc → stable.
- The main branch immediately bumps to the next minor version (still alpha).
Example timeline:
main (1.2.0-alpha)
│
├──► cut release/1.2 ──► 1.2.0-alpha → beta → preview → rc → 1.2.0 (tag: v1.2.0)
│ │
│ main bumps to 1.3.0-alpha ├──► 1.2.1 (maintenance)
│ │
▼ ▼
main (1.3.0-alpha) ──────────────────────────────────────────────► continues...
Fixes during stabilization
While a release branch is being stabilized (before the stable release), fixes may need to land in both the release branch and main. The approach depends on the nature of the fix:
| Scenario | Where to work | Then... |
| Bug fix needed in both main and release | main | Cherry-pick to release/X.Y |
| Release-only fix (e.g., regression introduced during stabilization) | release/X.Y | Merge back to main later |
| New feature | main only | Never touch the release branch |
Preferred workflow for shared fixes:
# Fix the bug on main
git checkout main
git commit -m "fix(audio): stop the buffer overflowing on resize"
git push
# Cherry-pick to the release branch
git checkout release/1.2
git cherry-pick <commit-hash>
git push
Cherry-picking from main is preferred because it keeps main as the source of truth and avoids accidentally pulling unfinished work into the release.
Merging release back to main
After tagging a stable release (e.g., v1.2.0), merge the release branch back into main to ensure any release-only fixes are not lost:
git checkout main
git merge release/1.2
git push
This merge can also be done periodically during stabilization if many fixes have accumulated on the release branch.
Maintenance releases
Release branches stick around after the stable release. If a bug is found in 1.2.0 while main is at 1.3.0-alpha:
- Fix the bug on main first (if applicable to both branches).
- Cherry-pick the fix to release/1.2.
- Release 1.2.1 (tag: v1.2.1).
- If the fix was made directly on release/1.2, merge back to main.
This allows shipping fixes to older versions without forcing users to upgrade.
Branch names
Branch names follow Conventional Branch:
| Type | Use for | Branches from | Example |
| feat/ | A new capability | main | feat/maze-radial-example |
| fix/ | A bug fix | main | fix/x11-keymap-validation |
| hotfix/ | A release-only fix (see Fixes during stabilization) | release/X.Y | hotfix/rc-regression-blit |
| release/ | A release branch, maintainers only | main | release/1.2 |
| chore/ | Everything else: refactoring, build, CI, docs, tests | main | chore/drop-maze-settings |
Rules for the description:
- Lowercase letters (a-z), digits (0-9) and hyphens (-) only. No uppercase, spaces, underscores or extra slashes.
- Hyphens never appear twice in a row, nor at the start or end.
- Short and descriptive: name the change, not the person or the date.
- If the work has a card on the issue tracker, you can prefix the description with issue-N-: fix/issue-184-raf-loop. This is optional.
Release branches are named release/X.Y exactly: major and minor only, no v, no patch number and no pre-release suffix. One release branch serves every patch release and pre-release stage of its version.
Commit messages
The commit that lands on main follows Conventional Commits:
<type>(<scope>): <subject> (#<PR>)
Pull requests are squash-merged, so this is the pull request title. Commits inside a branch are not constrained.
| Type | Use for |
| feat | A new capability |
| fix | A bug fix |
| refactor | A code change that neither fixes nor adds |
| perf | A performance improvement |
| docs | Documentation only |
| test | Tests only |
| build | Build system, packaging, releases |
| ci | .forgejo/workflows/ |
| chore | Anything else (version bumps, housekeeping) |
- scope (optional): the subsystem touched, e.g. audio, draw, maze, x11, wayland, emscripten, net.
- subject: imperative mood, lowercase, no trailing period: add runtime backend selection, not Added runtime backend selection.
- #<PR>: the pull request number, appended by the forge on merge.
- Breaking changes: add ! after the type or scope (feat(audio)!: …) and explain the break in a BREAKING CHANGE: footer.
Examples:
feat(audio): add runtime backend selection (#152)
fix(emscripten): stop the rAF draw loop outliving the window (#185)
docs(readme): rewrite homepage (#139)
Changelog
CHANGELOG.md follows Keep a Changelog:
- Upcoming changes go under ## [Unreleased] at the top. Releasing renames that section to ## [X.Y.Z] - YYYY-MM-DD.
- Entries are grouped under Added, Changed, Deprecated, Removed, Fixed and Security, in that order. Omit empty groups.
On top of that:
- The changelog describes the evolution of the product, not the commits. Write entries at the level of a capability a user would notice, never one line per function or per commit. Related entries can be nested under a parent bullet.
- An entry can end with the number of the issue tracker card it comes from: (#160). This is a card number, not a pull request number, and it is optional. One card can cover several entries, and a parent bullet's number covers its sub-bullets.
- Example programs get entries when they are added, but never a card number.
Language
The code is in C99, except src/cocoa/video_cocoa.m: Cocoa is an Objective-C API, so its backend is Objective-C (ADR 0002).
Header files and includes
Public headers live in inc/banjo/, with no subdirectories. Every header must parse standalone, with no other header required to precede it. A header must only include the headers it actually needs to parse.
Include order, each block alphabetically sorted and separated by a blank line:
- The header corresponding to the current implementation file (if any).
- Internal Banjo headers, with quotes ("").
- Public Banjo headers, with angle brackets (<>).
- Third-party headers.
- Standard library headers.
Doxygen
Use backslash directives only: \file, \brief, \param, \see, \snippet, never the @ form.
API conventions
- Single namespace: every public symbol/type is prefixed bj_ / BJ_, except the export macros of inc/banjo/api.h and the build macros they read, prefixed BANJO_ (BANJO_EXPORT, BANJO_NO_EXPORT, BANJO_STATIC, BANJO_EXPORTS).
- Booleans are bj_bool (a 32-bit unsigned).
- Fallible functions take struct bj_error** as their last parameter (see Error Management) when the caller needs to tell their failures apart. A function that fails only on invalid arguments or exhausted memory may report it through its return value alone, as bj_create_bitmap and bj_blit_bitmap do.
- A NULL pointer argument does no harm: unless the documentation gives it a meaning, such as an optional output or a shared default, the function does nothing, or returns its failure value (0, NULL, BJ_FALSE, or -1 where 0 is a valid result), and leaves its error location alone. Only a function whose documentation says so reports BJ_ERROR_INCORRECT_VALUE for it instead, as the maze constructors do. Document what NULL does for every pointer parameter, never "must not be NULL". The one exception is the header-only math of mat.h, quat.h and vec.h, whose inner-loop functions use their matrix and function pointers without checking them, as each of those headers says once.
- Don't (void)-suppress a returned status: CERT-ERR33-C forbids it. Fold the return value into control flow.
- Prefer bj_set_error_fmt over snprintf + bj_set_error.
- Names follow the conventions of the 1.x readability rework:
- Objects come in bj_create_* / bj_destroy_* pairs (bj_create_window, bj_destroy_window).
- Queries name the object first (bj_window_size, bj_stream_length).
- Predicates use is_ or has_ (bj_window_is_fullscreen, bj_window_has_flag).
- Actions start with their verb (bj_blit_bitmap, bj_poll_event).
- Type suffixes _i32, _u32, _f32, _f64 and _ld, and dimension suffixes such as _2d, tell variants apart (bj_random_uniform_i32, bj_compute_kinematics_2d).
Contributor workflow
This section explains how to contribute code to Banjo day-to-day.
The golden rule
Nobody pushes directly to main. All changes go through a pull request.
Making a change
- Create a branch from main, named as described in Branch names:
git checkout main
git pull
git checkout -b feat/my-feature
- Make your changes and commit them. Keep commits focused and atomic. If the change is visible to users, add an entry to CHANGELOG.md (see Changelog). An architectural decision that shapes the whole library gets an architecture decision record in docs/design/ (ADR 0001), and a change in observable behavior updates its specification in docs/spec/ and the matching cases in test/spec_<domain>.c (see docs/spec/README.md). The [Design] record format test checks that each record follows the format of ADR 0001.
- Push your branch and open a pull request whose title follows Commit messages:
git push -u origin feat/my-feature
- CI runs automatically. Your PR must pass all checks before merging.
- Once approved and green, the PR is squash-merged to main and the branch is deleted.
How tests are categorized
One category answers one question, and a change picks its categories by the questions it raises.
| Category | The question it answers | Write it when |
| [Spec] | the behavior of this API is exactly this | always: the base of every feature and API |
| [Property] | this law holds for thousands of arbitrary inputs | a mathematical or random core whose law examples do not carry |
| [Validation] | this input of the world is well formed, or reports its defect | anything that reads bytes of the world |
| [Stress] | this path survives the volume and the time | anything owning a saturable resource, and after any leak |
| [Unit] | this unmapped utility is correct | the small surfaces that live without a specification |
| [Design] | every architectural decision lives in a record, in the record format | once, as an invariant |
| [Link] | the optional platform libraries resolve | once, as a build invariant |
| Sync (mapping) | every specification row pairs with exactly one case | once, as the invariant of the two-way sync |
What to test for a feature or an API, in order:
- Write the [Spec] first: the rows of the behaviour the header documents, and the cases before the code when it helps. TDD is how a [Spec] gets written, not a category of its own.
- Add a [Property] when a law is enounceable and examples do not carry it.
- Add a [Validation] when the code reads bytes of the world.
- Add a [Stress] when a leak or a saturation is possible.
- What all four leave out, and that lives without a specification, is a [Unit].
A reported bug is not a category either: it becomes a case in the [Spec] of its domain and an entry in CHANGELOG.md under Fixed.
The target coverage, in words rather than percentages: one [Spec] file per published domain, one [Property] per domain that states laws, one [Validation] per format read, one [Stress] per kind of resource, and the three invariants. The specification files say what is true, never how many cases a domain needs.
When to write what: a memo
A change carries documents for the questions it settles, and nothing else. The table is the memo; the READMEs of docs/design/ and docs/spec/ detail each document.
| The change ... | Write ... | Where |
| fixes a bug a user reports | one [Spec] row + case, then the fix; a Fixed entry | the domain's specification and CHANGELOG.md |
| changes behavior users can observe | the rows + cases of the new behavior, as the code lands | the domain's specification |
| adds a capability or a public API | the [Spec] rows first, the cases, then the code; an Added entry | the domain's specification |
| shapes the architecture, a dependency or the API | an architecture decision record, before the code | docs/design/NNNN-kebab-title.md |
| renames or retires a public symbol | what ADR-0007's policy says: the old name stays, deprecation never breaks | the header and docs/spec/compat-001 |
| hits behavior that is ambiguous or untested yet | an open question in the specification, and drop it once settled | the domain's specification |
| is invisible to users (refactor, internal perf) | nothing: the existing specifications and cases pin what already holds | — |
The loop of a change, on one screen:
- Name the question the change raises, and pick from the table above.
- Write the rows (and the cases behind them) before the code when it helps; let the rows name the TEST_CASEs, not the other way around.
- Implement until the cases pass, with nothing specified that the code does not do.
- Run the invariants before committing: ctest --test-dir build, which runs the [Spec] mapping and [Design] record format checks along everything else.
- Give user-visible evolution its CHANGELOG.md entry, one line per capability, never per commit.
- Squash-merge the pull request; the specification, the header's Doxygen and the code tell the same story.
For maintainers: cutting a release
When main is ready to stabilize for version X.Y:
- Create the release branch:
git checkout main
git pull
git checkout -b release/X.Y
git push -u origin release/X.Y
- Bump main to the next version (e.g., 1.3.0-alpha):
git checkout main
# Edit inc/banjo/version.h
git commit -am "chore: bump version to 1.3.0-alpha"
git push
- On the release branch, progress through stages as stability improves:
- Update version.h to -beta, -preview, -rc, then remove the pre-release suffix for stable.
- Tag stable releases: git tag v1.2.0 && git push --tags
- Tag a pre-release only to publish it, with the version version.h gives: git tag v1.2.0-rc.1 && git push --tags
- Publish a release for the tag on the Releases page, marked as a pre-release for a pre-release tag: the release workflow checks the tag against version.h and attaches the packages.