diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3567f4c..33e7ca0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,3 +17,125 @@ 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