Skip to content

Latest commit

 

History

History
112 lines (75 loc) · 4.85 KB

CONTRIBUTING.md

File metadata and controls

112 lines (75 loc) · 4.85 KB
Raw

Contributing to Ezno

Consider checking out current standing issues before contributing. In general, leave an issue before putting in a PR.

If any problems come up in the following steps, please leave an issue :)

Setting up

Want to contribute, here is how to set up the environment?

First install Rust

then clone the repo with git:

git clone https://github.com/kaleidawave/ezno.git
# or using the GH CLI
gh repo clone kaleidawave/ezno

Now in the ezno directory, cargo run should show the CLI.

Development

You can run just the checker with

cargo run -p ezno-checker --example run-checker path/to/file.ts

Tip

This can be faster as doesn't have recompile the CLI options and things. (although the errors don't contain the nice source annotations) Note you can skip the cache with the additional --no-cache option (re-reads base .d.ts file)

If you want to check all the checker tests

cargo test -p ezno-checker-specification
# To include the Staging file (which is really useful for keeping new fixes/additions separate)
cargo test -p ezno-checker-specification -F staging
# and for all the tests (which includes all of to_implement.md)
cargo test -p ezno-checker-specification -F all

Important

cache might need to be regenerated between specification runs if working on internal methods (e.g. Array.map etc). See below

If you want to regenerate the binary definition file

cargo run -p ezno-checker -F ezno-parser --example generate_cache ./checker/definitions/overrides.d.ts ./checker/definitions/internal.ts.d.bin

If you want to test the lexing and parsing in Ezno's parser

# Parsing, prints parse errors or the debug view of the AST
cargo run -p ezno-parser --example parse path/to/file.ts
# Lexing, prints lex errors or the tokens
cargo run -p ezno-parser --example lex path/to/file.ts

Bacon (script runner)

The Bacon script runner is configured for this repo. This can watch your files and re-run things like checks or tests on file change. The configuration is managed in the bacon.toml file. The configuration has dedicated jobs for the checker specification tests mentioned above.

Installing Bacon

To install bacon, simply run cargo install --locked bacon, and you're ready to go.

Using Bacon

To use bacon, you can start it by running bacon check. This will spin up a job that listens to the source and runs checks on file changes! There are also hotkeys you can use to switch jobs, or manually trigger a re-run of a job (for jobs where watch functionality is disabled). We have some custom jobs defined as well:

Job Name Description Hotkey
test-spec-no-watch this job runs cargo test -p ezno-checker-specification and does not watch for file changes 1
test-staging-no-watch this job runs cargo test -p ezno-checker-specification -F staging and does not watch for file changes 2
test-all-no-watch this job runs cargo test -p ezno-checker-specification -F all and does not watch for file changes 3
test-spec this job runs cargo test -p ezno-checker-specification and watches for file changes 4
test-staging this job runs cargo test -p ezno-checker-specification -F staging and watches for file changes 5
test-all this job runs cargo test -p ezno-checker-specification -F all and watches for file changes 6

At any point, you can press ? to see a list of all available hotkeys.

Adding new jobs to our Bacon config

New jobs can easily be added to our bacon.toml config if we find there are repetitive actions we're doing frequently. The Bacon documentation does a good job of explaining how to do so.

Useful commands

  • Check source is valid with cargo check --workspace
  • Check that code is formatted in accordance with the configuration with cargo fmt --all --check
  • Run all tests cargo test --workspace --verbose
  • Use cargo clippy -- -A warnings to find blocking lints

The notify! macro

The checker crate has the crate::utilities::notify! macro, which can be used to trace information when the EZNO_DEBUG environment variable is set.

Rules for contributions

  • Code must be formatted with cargo format inline with the current format configuration
  • It must pass cargo clippy -- --allow warnings. In many cases adding allow to items is fine