5.0 KiB
The current document was written quickly and not exhaustively, yet, it's unfinished. Template here
Contributing to Squiggle
We welcome contributions from developers, especially people in react/typescript, rescript, and interpreters/parsers. We also are keen to hear issues filed by users!
Squiggle is currently pre-alpha.
Quick links
- Roadmap to the alpha
- The team presently communicates via the EA Forecasting and Epistemics slack (channels
#squiggleand#squiggle-ops), you can track down an invite by reaching out to Ozzie Gooen - Squiggle documentation
- Rescript documentation
- You can email
quinn@quantifieduncertainty.orgif you need assistance in onboarding or if you have questions
Bug reports
Anyone (with a github account) can file an issue at any time. Please allow Quinn, Sam, and Ozzie to triage, but otherwise just follow the suggestions in the issue templates.
Project structure
Squiggle is a monorepo with three packages.
- components is where we improve reactive interfacing with Squiggle
- squiggle-lang is where the magic happens: probability distributions, the interpreter, etc.
- website is the site
squiggle-language.com
Deployment ops
We use netlify, and it should only concern Quinn, Sam, and Ozzie.
Development environment, building, testing, dev server
You need yarn.
Being a monorepo, where packages are connected by dependency, it's important to follow README.mds closely. Each package has it's own README.md, which is where the bulk of information is.
We aspire for ci.yaml and README.mds to be in one-to-one correspondence.
If you're on NixOS
You can't run yarn outside of a FHS shell. Additionally, you need to patchelf some things. A script does everything for you.
./nixos.sh
Reasons for this are comments in the script. Then, you should be able to do all the package-level yarn run commands/scripts.
Try not to push directly to develop
If you absolutely must, please prefix your commit message with hotfix: .
Pull request protocol
Please work against develop branch. Do not work against master.
- For rescript code: Quinn and Ozzie are reviewers
- For js or typescript code: Sam and Ozzie are reviewers
- For ops code (i.e. yaml, package.json): Quinn and Sam are reviewers
Autopings are set up: if you are not autopinged, you are welcome to comment, but please do not use the formal review feature, send approvals, rejections, or merges.
Code Quality
- Aim for at least 8/10* quality in
/packages/squiggle-lang, and 7/10 quality in/packages/components. - If you submit a PR that is under a 7, for some reason, describe the reasoning for this in the PR.
- This quality score is subjective.
Rescript Style
Use -> instead of |>
Note: Our codebase used to use |>, so there's a lot of that in the system. We'll gradually change it.
Use x -> y -> z instead of let foo = y(x); let bar = z(foo)
Don't use anonymous functions with over three lines
Bad:
foo
-> E.O.fmap(r => {
let a = 34;
let b = 35;
let c = 48;
r + a + b + c
}
Good:
let addingFn = (r => {
let a = 34;
let b = 35;
let c = 48;
r + a + b + c
}
foo -> addingFn
Write out types for everything, even if there's an interface file
We'll try this for one month (ending May 5, 2022), then revisit.
Use the Rescript optional default syntax
Rescript is clever about function inputs. There's custom syntax for default and optional arguments. In the cases where this applies, use it.
From https://rescript-lang.org/docs/manual/latest/function:
// radius can be omitted
let drawCircle = (~color, ~radius=?, ()) => {
setColor(color)
switch radius {
| None => startAt(1, 1)
| Some(r_) => startAt(r_, r_)
}
}
Use named arguments
If a function is called externally (in a different file), and has either:
- Two arguments of the same type
- Three paramaters or more.
Module naming: Use x_y as module names
For example: Myname_Myproject_Add.res. Rescript/Ocaml both require files to have unique names, so long names are needed to keep different parts separate from each other.
See this page for more information. (Though note that they use two underscores, and we do one. We might refactor that later.
Module naming: Don't rename modules We have some of this in the Reducer code, but generally discourage it.
Use interface files (.resi) for files with very public interfaces