CONTRIBUTING braindump

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