kerolox/CONTRIBUTING.md

• TODO: document VSCode extension development practices
• TODO: document Helix Kerolox language setup
• TODO: document licensing and attribution guidelines
• TODO: write testing docs

Contributing to the Tree-sitter Grammar

The Kerolox tooling makes use of a custom tree-sitter grammar for fast incremental parsing.

The tree-sitter grammar lives in the tree-sitter-kerolox directory in the repository. The main file of interest is grammar.js, which defines the actual Kerolox grammar. The tree-sitter documentation has very useful documentation on how to work with this grammar definition.

Any time the grammar is modified, the tree-sitter parser needs to be regenerated using the tree-sitter CLI. Otherwise, the changes to the grammar won't actually be compiled. To regenerate the parser from the grammar, ensure the CLI is installed, and run this command in the tree-sitter-kerolox directory:

tree-sitter generate --abi 14

We use an ABI version of 14 because it's known to work with older versions of Helix, Marceline's preferred text editor. This is a deliberately overly cautious policy, but we're open to changing it if there's a good reason to.

The generated files should be committed and pushed as normal, since it's conventional for third-party tools to pull and compile pregenerated tree-sitter parsers directly from their upstream repositories.

WIP contribution guidelines

• what kind of schedule can I put myself on to maximize collaboration opportunities?
  • make a list of everyone I know who's interested and check in often
• most spreading of knowledge of Kerolox and SV is going to be mainly word of mouth
• keep constant monitoring of other constraint languages and compare/contrast
• figure changelog game out

Types of contribution

• community moderation
  • Discord
  • a future forum if we opened one
  • issue tracker
• editor integration
  • Vim
  • Neovim
  • VSCode
  • Zed
  • Emacs
  • Micro
• internal docs
  • rustdoc
  • onboarding for new contributors
  • build instructions
• example programs
  • logic or word puzzles
  • real-world planning problems
  • backporting Jack, Amie, and Nea's programs as examples
  • CSPLib library
    • would want to either integrate upstream or maintain a fork
• site hosting
  • rustdoc subdomain
  • stdlib and examples subdomain
  • releases subdomain (?)
  • blog subdomain
• bug reports
  • users should be able to easily report any problems they see
  • this could be done by reporting a bug directly
  • community environments could be manually converted into bug reports
  • emails could become the main source of contact
  • an important consideration is that logins are generally a filter
• trying out the language
  • just trying Kerolox counts as collaboration
  • word of mouth gains leverage here no matter what
• testing infrastructure
  • fuzzing
  • coverage
  • writing fixtures
  • adding new test suites
• interactive tutorial
  • a pet peeve of mine is when I can't learn a language without interaction
  • Ace said this would help her get over the initial skill hump
• adding new static checks
  • "check" is a pretty vague term :/
  • requires Rust and Z3 literacy
  • good for more math-y contributors
  • no architecture needed
  • the check stage should be extremely modular
• formalization of the semantics
  • improve understanding of how Kerolox compares and contrasts to other constraint languages
• standard library
  • documentation is the most important thing to contribute
  • should the stdlib be in its own repository?
    • how deeply does it integrate into solvers?
    • how much custom logic needs to be implemented
  • managing candidate changes effectively is critical and should be democratic
    • silt will have input on how to do something like this better than how Rust does it
• releases
  • cross-compilation
  • effective CI
  • testing?

Code architecture

• core
  • parse -> resolve -> infer -> desugar
• check
  • dependent on Z3 fixed-point analysis
    • should be documented on its own for newcomers
  • needs a dedicated framework for managing check suites
  • maybe configure the priorities of each check's priorities
  • checking should definitely be fuzz-tested
    • the time may come for untrusted Kerolox on servers
    • trustworthiness is critical
  • benchmark tactic strategies and parameters in matrix
    • regularly update and update strats
• frontend
  • integrates the "check" and "core" crates
  • converts structured diagnostic types into generic, user-facing types
  • implements code actions
  • data-driven code action tests
• formatting
  • somehow need to represent LSP edit data, needs more research
  • should Kerolox code style be configurable?
  • need a binary entrypoint to formatting a workspace
• documentation generation (kerodox)
  • Tera is overcomplicated according to silt
  • maybe it's fine anyways for similarities to Jinja 2 and Django
  • good documentation on how to use the templating language is critical
    • could possibly be automatically generated based on doc comments on structs
  • needs to run after the infer stage to have type info
  • output formats
    • HTML
    • man(5)
    • Markdown
    • Typst
• LSP
  • live diagnostics
  • asynchronous checking
  • incremental formatting
• browser integration
  • CodeMirror UX
  • executing Kerolox in Wasm
  • embedding in examples and tutorials
  • idiomatic browser tech API (either Rust frontend or JS/TS)
• editor integration
  • per-editor configuration directories
  • tree-sitter should be integrated when possible
  • documentation should route to each one straight-forwardly
  • should be robustly tested when possible