git.iko.soy/htmlang
on v2026.4.26151538 help sign in
htmlang/CONTRIBUTING.md
63 lines 2.6 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- `crates/htmlang-wasm/` — thin wrapper exposing `compile` to the web playground.
23- `src/` — CLI, dev server, formatter, and HTML-to-hl converter.
24- `src/bin/htmlang_lsp/` — language server binary (`htmlang-lsp`).
25- `editors/vscode/` — VS Code extension.
26- `tests/snapshots.rs` — integration / snapshot tests for the compiler.
27- `examples/` — sample `.hl` files used as smoke tests and documentation.
29## Adding a feature
311. Add a test first. Most language features fit as a new `#[test]` in
32 `tests/snapshots.rs`; prefer integration tests that exercise the full
33 parser-to-HTML pipeline. Pure parser / codegen helpers can live as unit
34 tests alongside the code.
352. Thread the feature through the parser, then codegen, then the LSP (hover,
36 completions, diagnostics).
373. Document it in `DESIGN.md`. If it's user-facing, also update `README.md`.
384. If it changes the CLI surface, update the `--help` output and the shell
39 completions.
41## Style
43- Prefer enum-based ASTs and pattern matching over stringly-typed dispatch.
44- Keep `@` prefixes and bracket-attribute syntax consistent with existing
45 directives. Add `KNOWN_DIRECTIVES` entries when you add a new `@foo`.
46- Diagnostics should include `line` and, when practical, `column` and a
47 `source_line` excerpt. Use `Severity::Help` for suggestions, not `Warning`.
48- No unwrap() on parsed user input. Use `Result<_, ParseError>` and record a
49 diagnostic so the compiler keeps going.
51## Reporting bugs
53Bug reports are most useful when they include:
55- The exact `.hl` input that reproduces the issue (minimized if possible).
56- The command you ran and the output you saw.
57- The output you expected instead.
58- `htmlang --version` and your OS.
60## License
62By contributing, you agree that your changes will be licensed under the same
63terms as the rest of the project.