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](https://github.com/tree-sitter/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](https://tree-sitter.github.io/tree-sitter/creating-parsers/index.html) 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](https://github.com/tree-sitter/tree-sitter/blob/master/crates/cli/README.md). 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:

```bash
tree-sitter generate --abi 14
```

We use an [ABI version](https://tree-sitter.github.io/tree-sitter/using-parsers/7-abi-versions.html) of 14 because it's known to work with older versions of [Helix](https://helix-editor.com), 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