From 24a587a9d984fee087571fe818e7b4810bb9de55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Juli=C3=A1n=20Espina?= Date: Thu, 19 Feb 2026 13:01:21 -0600 Subject: [PATCH 1/2] Cleanup contributing and roadmap pages --- docs/contributing/CONTRIBUTING.md | 74 ------------------------- docs/contributing/contributing.md | 92 +++++++++++++++++++++++++++++++ docs/contributing/ecmascript.md | 51 +++++++++++++++++ docs/contributing/testing.md | 49 +++++++++------- docusaurus.config.ts | 36 ++++++------ src/pages/roadmap.md | 52 +++++++++-------- 6 files changed, 221 insertions(+), 133 deletions(-) delete mode 100644 docs/contributing/CONTRIBUTING.md create mode 100644 docs/contributing/contributing.md create mode 100644 docs/contributing/ecmascript.md diff --git a/docs/contributing/CONTRIBUTING.md b/docs/contributing/CONTRIBUTING.md deleted file mode 100644 index 7ed9f4aa..00000000 --- a/docs/contributing/CONTRIBUTING.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Contributing to Boa - -Boa welcomes contribution from everyone. Here are the guidelines if you are -thinking of helping out: - -## Contributions - -Contributions to Boa or its dependencies should be made in the form of GitHub -pull requests. Each pull request will be reviewed by a core contributor -(someone with permission to land patches) and either landed in the main tree or -given feedback for changes that would be required. All contributions should -follow this format. - -Should you wish to work on an issue, please claim it first by commenting on -the GitHub issue that you want to work on it. This is to prevent duplicated -efforts from contributors on the same issue. - -Head over to [issues][issues] and check for "good first issue" labels to find -good tasks to start with. If you come across words or jargon that do not make -sense, please ask! - -If you don't already have Rust installed [_rustup_][rustup] is the recommended -tool to use. It will install Rust and allow you to switch between _nightly_, -_stable_ and _beta_. You can also install additional components. In Linux, you -can run: - -```shell -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -Then simply clone this project and `cargo build`. - -### Running the compiler - -You can execute a Boa console by running `cargo run`, and you can compile a list -of JavaScript files by running `cargo run -- file1.js file2.js` and so on. - -### Web Assembly - -If you want to develop on the web assembly side you can run `yarn serve` and then go -to http://localhost:8080. - -### Setup - -#### VSCode Plugins - -Either the [Rust (RLS)][rls_vscode] or the [Rust Analyzer][rust-analyzer_vscode] -extensions are preferred. RLS is easier to set up but some of the development is -moving towards Rust Analyzer. Both of these plugins will help you with your Rust -Development - -#### Tasks - -Boa has some pre-defined tasks in ".vscode/tasks.json" - -- Build - shift+cmd/ctrl+b should build and run cargo. You should be able to make changes and run this task. -- Test - (there is no shortcut, you'll need to make one) - Runs `Cargo Test`. - I personally set a shortcut of shift+cmd+option+T (or shift+ctrl+alt+T) - -If you don't want to install everything on your machine, you can use the Dockerfile. -Start VSCode in container mode (you may need the docker container plugin) and use the Dockerfile. - -## Communication - -We have a Discord server, feel free to ask questions [here](https://discord.gg/tUFFk9Y) - -[issues]: https://github.com/boa-dev/boa/issues -[rustup]: https://rustup.rs/ -[rls_vscode]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust -[rust-analyzer_vscode]: https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md new file mode 100644 index 00000000..d92daee3 --- /dev/null +++ b/docs/contributing/contributing.md @@ -0,0 +1,92 @@ +--- +sidebar_position: 1 +--- + +# Contributing to Boa + +Boa welcomes contribution from everyone. Here are the guidelines if you are +thinking of helping out: + +## Contributions + +Contributions to Boa or its dependencies should be made in the form of GitHub +pull requests. Each pull request will be reviewed by a core contributor +(someone with permission to land patches) and either landed in the main tree or +given feedback for changes that would be required. All contributions should +follow this format. + +Should you wish to work on an issue, please claim it first by commenting on +the GitHub issue that you want to work on it. This is to prevent duplicated +efforts from contributors on the same issue. + +Head over to [issues][issues] and check for "good first issue" labels to find +good tasks to start with. If you come across words or jargon that do not make +sense, please ask! + +If you don't already have Rust installed [_rustup_][rustup] is the recommended +tool to use. It will install Rust and allow you to switch between _nightly_, +_stable_ and _beta_. You can also install additional components. In Linux, you +can run: + +```shell +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +Then simply clone this project and `cargo build`. + +## Running the compiler + +You can execute a Boa console by running `cargo run`, and you can compile a list +of JavaScript files by running `cargo run -- file1.js file2.js` and so on. + +## Building the docs + +To build the development documentation, run: + +```shell +cargo doc --all-features --document-private-items --workspace +``` + +This will also document all the dependencies on the workspace, which could be +heavier in size. To only generate documentation for the workspace members, just +add the `--no-deps` flag: + +```shell +cargo doc --all-features --document-private-items --workspace --no-deps +``` + +## Debugging + +Knowing how to debug the interpreter should help you resolve problems quite quickly. +See [Debugging](docs/category/debugging). + +## IDE Setup + +You can work on Boa with any text editor capable of editing Rust and Javascript code. +An easy way of getting started is to use [Visual Studio Code](https://code.visualstudio.com/) +with the [Rust Analyzer][rust-analyzer_vscode] extension. + +## AI + +We are usually not against using AI tools. However, their +general availability makes it much easier to fill our review capacity with +low-effort contributions. Therefore, every contributor must adhere to the following +rules: +- No spamming PRs. This includes the use of AI agents to open multiple PRs in + succession. +- No PRs with massive line changes (5k+) without prior discussion and acknowledgement. +- All PR authors must be able to explain what their contribution does in detail. + +The maintainers reserve the right to closing any PRs that do not follow these rules, +and recurrent offenses will result in a global ban from contributing to all +Boa-related projects. + +## Communication + +Most of our communication happens in Matrix, feel free to ask questions in our +[Boa space][matrix]. + +[issues]: https://github.com/boa-dev/boa/issues +[rustup]: https://rustup.rs/ +[rust-analyzer_vscode]: https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer +[matrix]: https://matrix.to/#/#boa:matrix.org diff --git a/docs/contributing/ecmascript.md b/docs/contributing/ecmascript.md new file mode 100644 index 00000000..b6e6cb33 --- /dev/null +++ b/docs/contributing/ecmascript.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 3 +--- + +# Understanding the ECMAScript Specification + +Many contributions to Boa involve implementing parts of the [ECMAScript +Language Specification](https://tc39.es/ecma262/), which defines how JavaScript +behaves. At first, the spec can seem intimidating, but it quickly becomes +easier to follow once you get familiar with its structure and notation. + +The specification is written in a pseudo-language designed to describe behavior +without being tied to any particular programming language. It introduces some +important concepts: + +- **Abstract operations** – general algorithms (i.e. [`IsCallable`](https://tc39.es/ecma262/#sec-iscallable)), + which usually map to Rust functions or methods. +- **Internal slots** – hidden object fields like + [`[[Prototype]]`](https://tc39.es/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots) + that correspond to private struct or enum fields in Rust, not accessible to + JavaScript. +- **Completion records** – describe how values or exceptions are returned + ([link](https://tc39.es/ecma262/#sec-completion-record-specification-type)), + and typically map to `JsResult` types in Rust. +- **Symbols `?` and `!`** – `? Foo(...)` propagates exceptions mapped to + propagate `?` operator in rust, while `! Foo(...)` are infallible operations + and are usually mapped to + [`Result::expect()`](https://doc.rust-lang.org/std/result/enum.Result.html#method.expect) + call. + +For an in-depth introduction to these concepts and more, check out [V8’s “Understanding +the ECMAScript spec” +series](https://v8.dev/blog/tags/understanding-ecmascript), starting with [Part +1](https://v8.dev/blog/understanding-ecmascript-part-1). + +When implementing the spec in Boa, try to map your code to the corresponding +spec steps whenever possible, and indicate in comments which steps are implemented. +This makes the code easier to understand, ensures it aligns with the +specification, and helps reviewers and future contributors follow the logic. + +If a spec step does not map directly because of Rust limitations or performance +reasons, just add a note in the code explaining the difference. Being clear +about these cases helps others understand your implementation while still +following the spec as closely as possible. + +For examples of how to implement the specification, check out the built-in +implementations in Boa +[here](https://github.com/boa-dev/boa/tree/main/core/engine/src/builtins). + +If anything in the specification is confusing, don’t hesitate to ask in the +[Boa Matrix](https://matrix.to/#/#boa:matrix.org) channel. diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md index 69e5476a..28b7f7b5 100644 --- a/docs/contributing/testing.md +++ b/docs/contributing/testing.md @@ -4,30 +4,14 @@ sidebar_position: 2 # Testing -Boa provides its own test suite, as well as a way to run the official ECMAScript conformance test suite. - -## Boa's tests suite - -Boa's test suite is implemented in the various `tests.rs` files throughout the project and driven by Rust's -testing capabilities. So to run the Boa test suite, you can just run the normal `cargo test`. - -## ECMAScript's `test262` Conformance Test Suite - -The ECMAScript test262 is a git submodule of tc39's current version of the test suite and represents the implementation -conformance. - -To run the full ECMAScript test suite, you can use the below command in Boa's root directory: +Boa provides its own test suite, and can also run the official ECMAScript test suite. To run the Boa test +suite, you can just run the normal `cargo test`, and to run the full ECMAScript test suite, you can run it +with this command: ```shell cargo run --release --bin boa_tester -- run -v 2> error.log ``` -Note that this requires the `test262` submodule to be checked out, so you will need to run the following first: - -```shell -git submodule init && git submodule update -``` - This will run the test suite in verbose mode (you can remove the `-v` part to run it in non-verbose mode), and output nice colorings in the terminal. It will also output any panic information into the `error.log` file. @@ -46,3 +30,30 @@ be more readable if you disable parallelism with the `-d` flag. All together it ```shell cargo run --release --bin boa_tester -- run -vv -d -s test/language/types/number 2> error.log ``` + +To save test results for later comparison, use the `-o` flag to specify an output directory: + +```shell +cargo run --release --bin boa_tester -- run -o ./test-results +``` + +## Comparing Test Results + +You can compare two test suite runs to see what changed: + +```shell +cargo run --release --bin boa_tester -- compare +``` + +Both arguments can be either result files (e.g., `latest.json`) or directories containing test results. +When directories are provided, the tester automatically uses the `latest.json` file from each directory. + +For example: + +```shell +# Compare using directories +cargo run --release --bin boa_tester -- compare ./test-results-main ./test-results-feature + +# Compare using explicit files +cargo run --release --bin boa_tester -- compare ./test-results-main/latest.json ./test-results-feature/latest.json +``` diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c558f96c..5f8af6ec 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -73,35 +73,35 @@ const config: Config = { type: "docSidebar", sidebarId: "infoSidebar", position: "left", - label: "Learn More", + label: "Documentation", }, { to: "/blog", label: "Blog", position: "left" }, { to: "/about", label: "About", position: "left" }, { - href: "/playground", - label: "Playground", - position: "right", - }, - { - href: "/roadmap", + to: "/roadmap", label: "Roadmap", - position: "right", + position: "left", }, { - href: "https://github.com/boa-dev/boa/tree/main/examples", - label: "Examples", + to: "/playground", + label: "Playground", position: "right", }, { - href: "/conformance", + to: "/conformance", label: "Conformance", position: "right", }, { - href: "/benchmarks", + to: "/benchmarks", label: "Benchmarks", position: "right", }, + { + href: "https://github.com/boa-dev/boa/tree/main/examples", + label: "Examples", + position: "right", + }, { href: "https://docs.rs/boa_engine/latest", label: "API Docs", @@ -118,18 +118,18 @@ const config: Config = { footer: { links: [ { - title: "Docs", + title: "General", items: [ { label: "About", to: "/about", }, { - label: "Learn More", + label: "Docs", to: "/docs/intro", }, { - label: "API Documentation", + label: "API Docs", href: "https://docs.rs/boa_engine/latest", }, ], @@ -138,13 +138,13 @@ const config: Config = { title: "Community", items: [ { - label: "Discord", - href: "https://discord.gg/tUFFk9Y", + label: "Matrix", + href: "https://matrix.to/#/#boa:matrix.org", }, { label: "Mastodon", href: "https://fosstodon.org/@boa_engine", - }, + } ], }, { diff --git a/src/pages/roadmap.md b/src/pages/roadmap.md index b2fcf4c8..403c1db7 100644 --- a/src/pages/roadmap.md +++ b/src/pages/roadmap.md @@ -12,13 +12,13 @@ description: Roadmap and planned features for the Boa project. - Required Skills: Rust, memory management, data structures - Preferred Skills: Garbage collection algorithms, language runtimes -### Description +#### Description Boa currently uses a prototype garbage collector, with experimental work happening in the separate [Oscars repository](https://github.com/boa-dev/oscars). While functional, the GC architecture needs significant redesign to better support performance, maintainability, and future language features. This project focuses on evaluating, refining, and integrating a production-ready garbage collector into Boa. -### Expected Outcomes +#### Expected Outcomes - Analyze the current GC design and limitations - Improve or redesign the GC architecture (e.g. tracing strategy, allocation model, rooting) @@ -26,15 +26,17 @@ This project focuses on evaluating, refining, and integrating a production-ready - Add stress tests and benchmarks for GC behavior - Produce documentation explaining the design and trade-offs -### Possible Extensions +#### Possible Extensions - Incremental or generational GC strategies - GC-aware optimizations in the VM - Tooling to visualize heap and GC activity -### Project Discussion: -[Matrix Boa/GC](https://matrix.to/#/!ESLxDMqdSvKbprdiyg:matrix.org?via=matrix.org&via=rrogal.ski&via=t2bot.io) -[Matrix Boa/General](https://matrix.to/#/!ZBLAwGpYvzsLqZAZZg:matrix.org?via=matrix.org&via=t2bot.io&via=mozilla.org) +#### Project Discussion: +- [Matrix Boa/GC](https://matrix.to/#/!ESLxDMqdSvKbprdiyg:matrix.org?via=matrix.org&via=rrogal.ski&via=t2bot.io) +- [Matrix Boa/General](https://matrix.to/#/!ZBLAwGpYvzsLqZAZZg:matrix.org?via=matrix.org&via=t2bot.io&via=mozilla.org) + +--- ## Public API Audit and 1.0 Stabilization @@ -43,12 +45,12 @@ This project focuses on evaluating, refining, and integrating a production-ready - Required Skills: Rust, API design - Preferred Skills: SemVer, library maintenance, documentation -### Description +#### Description Boa is approaching its 1.0 release. A key requirement for this milestone is ensuring that our public APIs are well-defined, intentional, and stable, as breaking changes become significantly more costly after 1.0. This project focuses on auditing Boa’s public API surface, identifying areas that may cause long-term maintenance or compatibility issues, and helping prepare the engine for a stable 1.0 release. -### Expected Outcomes +#### Expected Outcomes - Identify and document all public-facing APIs (types, traits, functions, feature flags) - Review APIs for stability, consistency, and long-term viability @@ -56,12 +58,17 @@ This project focuses on auditing Boa’s public API surface, identifying areas t - Help resolve or unblock remaining items needed for the 1.0 milestone - Improve documentation around public APIs and versioning guarantees -### Possible Extensions +#### Possible Extensions - Introduce tooling or CI checks to detect accidental public API changes - Improve feature gating or visibility (pub vs pub(crate)) across the codebase - Assist in defining Boa’s post-1.0 stability and deprecation policy +#### Open Issue: +https://github.com/boa-dev/boa/issues/4524 + +--- + ## JavaScript Engine Performance Improvements - Difficulty: Medium–Hard @@ -69,16 +76,13 @@ This project focuses on auditing Boa’s public API surface, identifying areas t - Required Skills: Rust, profiling, algorithms - Preferred Skills: Compiler or VM internals, benchmarking -## Open Issue: -https://github.com/boa-dev/boa/issues/4524 - -### Description +#### Description Performance is a core goal of Boa. While already competitive in many areas, there are clear opportunities to improve execution speed, memory usage, and startup time. This project focuses on identifying performance bottlenecks and implementing targeted optimizations across the VM, bytecode execution, and runtime systems. -### Expected Outcomes +#### Expected Outcomes - Much improved results on boajs.dev/benchmarks - Identify high-impact performance bottlenecks @@ -86,15 +90,17 @@ This project focuses on identifying performance bottlenecks and implementing tar - Add or improve benchmarks to prevent regressions - Document performance changes and results -### Possible Extensions +#### Possible Extensions - Reduced allocation pressure and memory churn - Improve documentation and tooling for profiling and benchmarking -### Project Discussion +#### Project Discussion - [Matrix Boa/Performance](https://matrix.to/#/!odQJQiuPFJtUBzgoXY:matrix.org?via=matrix.org&via=gitter.im&via=rrogal.ski) - [Matrix Boa/General](https://matrix.to/#/!ZBLAwGpYvzsLqZAZZg:matrix.org?via=matrix.org&via=t2bot.io&via=mozilla.org) +--- + ## ECMAScript Conformance and Spec Compliance - Difficulty: Medium @@ -102,13 +108,13 @@ This project focuses on identifying performance bottlenecks and implementing tar - Required Skills: Rust, reading specifications - Preferred Skills: JavaScript engine internals -### Description +#### Description Boa already performs well on ECMAScript conformance tests, but maintaining and improving compliance is an ongoing effort as the specification evolves. This project focuses on closing remaining gaps, improving correctness in edge cases, and strengthening test coverage. -### Expected Outcomes +#### Expected Outcomes - Identify areas where Boa diverges from the ECMAScript specification - Implement missing or partially compliant features @@ -116,11 +122,13 @@ This project focuses on closing remaining gaps, improving correctness in edge ca - Reduce known test failures and inconsistencies - Document tricky or non-obvious spec decisions -### Possible Extensions +#### Possible Extensions - Focus on a specific ECMAScript feature set (e.g. async, modules, Intl groundwork) - Improve error reporting and diagnostics for spec failures +--- + ## Developer Tooling and Engine Observability - Difficulty: Medium @@ -128,18 +136,18 @@ This project focuses on closing remaining gaps, improving correctness in edge ca - Required Skills: Rust, tooling, debugging - Preferred Skills: Runtime diagnostics, profiling tools -### Description +#### Description As Boa grows, better tooling is needed to understand and debug engine behavior. This project focuses on improving observability for developers working on the engine. -### Expected Outcomes +#### Expected Outcomes - Improve logging and diagnostics in the VM and runtime - Add optional tracing or debug modes - Improve internal metrics (allocation counts, GC timing, bytecode execution stats) - Document tooling for contributors and users -### Possible Extensions +#### Possible Extensions - Debug-friendly execution modes - Performance and memory visualization tooling From 5e5df066f3d5e007f8c5efc3dcb01248cf94f99d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Juli=C3=A1n=20Espina?= Date: Thu, 19 Feb 2026 13:13:35 -0600 Subject: [PATCH 2/2] fix link to debugging --- docs/contributing/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index d92daee3..f5eddc5d 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -58,7 +58,7 @@ cargo doc --all-features --document-private-items --workspace --no-deps ## Debugging Knowing how to debug the interpreter should help you resolve problems quite quickly. -See [Debugging](docs/category/debugging). +See [Debugging](/category/debugging). ## IDE Setup