git.iko.soy/htmlang
on v2026.9.25235210 help sign in
htmlang/CONTRIBUTING.md
77 lines 3.5 kB history raw
1# Contributing
3Thanks for your interest in improving htmlang. This file covers the practical
4bits: how to run the project locally, where the code lives, and what style of
5changes land smoothly.
7## Development
9```
10cargo build # build the CLI + LSP binaries
11cargo test # run all tests (unit + snapshot + integration)
12cargo run -- page.hl # compile a .hl file to page.html
13cargo run -- serve examples # run the dev server at http://127.0.0.1:3000
14```
16CI runs `cargo test`, `cargo fmt --check`, and `cargo clippy -- -D warnings` on
17Linux, macOS, and Windows. Your change should pass all three.
19## Repository layout
21- `crates/htmlang-core/` — parser, AST, code generator. No I/O lives here.
22 - `ast.rs` — the element kinds; every plain HTML element is one row in `TAGS`.
23 - `vocab.rs` — the attribute vocabulary (htmlang attributes, CSS properties,
24 HTML attributes) and the state/media prefixes.
25 - `expr.rs` — the expression language for conditions and computed values.
26 - `std.hl` — the standard library, written in htmlang and loaded before
27 every file.
28- `crates/htmlang-wasm/` — thin wrapper exposing `compile` to the web playground.
29- `src/` — CLI, dev server, formatter, and `upgrade` (syntax migrations).
30- `src/bin/htmlang_lsp/` — language server binary (`htmlang-lsp`). Its
31 completions come from the compiler's tables; hover and completion text live
32 in `docs.rs`.
33- `editors/vscode/` — VS Code extension.
34- `tests/snapshots.rs` — integration / snapshot tests for the compiler.
35- `tests/regressions.rs` — one test per fixed bug.
36- `tests/docs.rs` — compiles every example in `DESIGN.md` and `README.md`.
37- `examples/` — sample `.hl` files used as smoke tests and documentation.
39## Adding a feature
411. Add a test first. Most language features fit as a new `#[test]` in
42 `tests/snapshots.rs`; prefer integration tests that exercise the full
43 parser-to-HTML pipeline. Pure parser / codegen helpers can live as unit
44 tests alongside the code.
452. Prefer the smallest mechanism: a component belongs in `std.hl`, an HTML
46 element is a row in `TAGS`, and a CSS property needs no code at all. Only
47 thread a feature through the parser and codegen when it needs to be, and
48 describe it in the LSP's `docs.rs`.
493. Document it in `DESIGN.md` (the examples there are compiled by the tests).
50 If it's user-facing, also update `README.md`.
514. If it removes or renames syntax, add a rewrite to `src/upgrade.rs` and a
52 hint to `REMOVED_SYNTAX` in the parser.
535. If it changes the CLI surface, update the `--help` output.
55## Style
57- Prefer enum-based ASTs and pattern matching over stringly-typed dispatch.
58- Keep `@` prefixes and bracket-attribute syntax consistent with existing
59 directives. Add `KNOWN_DIRECTIVES` entries when you add a new `@foo`.
60- Diagnostics should include `line` and, when practical, `column` and a
61 `source_line` excerpt. Use `Severity::Help` for suggestions, not `Warning`.
62- No unwrap() on parsed user input. Use `Result<_, ParseError>` and record a
63 diagnostic so the compiler keeps going.
65## Reporting bugs
67Bug reports are most useful when they include:
69- The exact `.hl` input that reproduces the issue (minimized if possible).
70- The command you ran and the output you saw.
71- The output you expected instead.
72- `htmlang --version` and your OS.
74## License
76By contributing, you agree that your changes will be licensed under the same
77terms as the rest of the project.