Cleanup contributing and roadmap pages (#225)

* Cleanup contributing and roadmap pages

* fix link to debugging

* fix link to debugging

Author: jedel1043

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

docs/contributing/contributing.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.

docs/contributing/ecmascript.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 <base-results> <new-results>
+```
+
+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
+```

docs/contributing/testing.md

@@ -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",
-            },
+            }
           ],
         },
         {