Developer docs
December 7, 2025 · View on GitHub
This consists of a few separate documents
- Code architecture describes the overall dependency of packages.
- Code structure - more detailed description of the packages.
- DOM node implementation - The DOM tree itself (see below)
- Testing - Guidelines for testing
DOM Tree - Unidiomatic Go
Idiomatic Go uses small interfaces, and this leads to many elegant solutions.
But the problem domain itself, implementing browser behaviour and implementing the standards does place a significant constraint on the types of solutions applicable.
As a result, there are many types, and specifically interfaces, that are larger than desired. This is particularly the case in the DOM tree itself.
Polyfills
Where possible, JavaScript APIs are implemented through polyfills.
Polyfills are configured polyfills.go, and
JavaScript code is embedded from the folder
polyfills
Commit guidelines
Change logs are generated automatically from git commit messages. conventional commit defines the format for commit messages.
Conventional commits need not be followed rigurously, but notes that should appear in changelog must follow the format.1
Commit format
<type>(<optional scope>): Title
Description
<FOOTER>: Footer title
Footer description
- Commit title must be short.
- A breaking change must be indicated through either
- An optional exclamation mark after the type and scope, e.g.,
feat!: Something - A
BREAKING CHANGE:footer, if more text is necessary
- An optional exclamation mark after the type and scope, e.g.,
- If the title isn't enough, the body should describe why the commit is good.
- Both title and body shall be written in the imperative format.
Commit types
The commit types are based on the Angular commit message format with some changes
| Type | Description |
|---|---|
| build | Changes that affect the build scripts |
| ci | Changes to the CI configuration |
| cleanup | Remove dead code, print statements, or comments |
| docs | Documentation only changes |
| drop | An existing feature is removed or no longer supported |
| feat | A new feature |
| fix | A bug fix |
| perf | A code change that improves performance |
| refactor | A code change that improves code and doesn't change behaviour2 |
| test | Adding missing tests, correcting existing tests, or refactors tests |
| work | An incremental change working towards a feature |
A commit may naturally fall into multiple categories. A feature must have tests,
and ideally, test and implementation are in the same commit of type feat or
work.
The work type is intended for incremental changes for a larger feature; but
the commits are on a different level than what we want to describe in the change
log.[^3]
Commit scopes
| Scope | Description |
|---|---|
| dom | Internal DOM model |
| html | Internal HTML representation |
| v8 | V8 script host |
| readme | Readme file changes. Only applicable for docs type |
| codegen | Changes to the code generator |
A "feature" scoped with dom or html signifies that any relevant JavaScript
bindings are missing.
High quality PR
The guidelines for a larger feature is
- create multiple
workcommits with short messages - refactor before feature
- rebase before merge
- one
featnon-fast forward merge commit with detailed description of the feature.
Instead of creating the feat merge commit, you can write the commit message in the
PR title/body.
By placing refactors before the feature itself, they can be merged individually, separating refactor commits from changes to behaviour.
* feat: Add feature Y (PR)
|\
| * work: Add 'A' to API
| * work: Add 'B' to API
|/
* refactor: Make A easier to implement
* refactor: Make B easier to implement
* feat: Add feature X
The diff of the feature commit itself will list the cumulative changes of all the work commits.