docs: getting started (#4600)

rome · Jun 22, 2023 · 89faa6c · 89faa6c
1 parent 50eb45f
commit 89faa6c
Show file tree

Hide file tree

Showing 50 changed files with 753 additions and 720 deletions.
diff --git a/.cargo/config.toml b/.cargo/config.toml
@@ -1,12 +1,14 @@
 [alias]
-lint = "clippy --workspace --all-targets --verbose -- --deny warnings -W clippy::cargo -W clippy::dbg_macro -A clippy::cargo_common_metadata -A clippy::multiple_crate_versions"
-format = "fmt --all --verbose"
+bench_analyzer = "run -p xtask_bench --release -- --feature analyzer"
+bench_formatter = "run -p xtask_bench --release -- --feature formatter"
+bench_parser = "run -p xtask_bench --release -- --feature parser"
 codegen = "run -p xtask_codegen --"
+codegen-bindings = "run -p xtask_codegen --features schema -- bindings"
 codegen-configuration = "run -p xtask_codegen --features configuration -- configuration"
 codegen-schema = "run -p xtask_codegen --features schema -- schema"
-codegen-bindings = "run -p xtask_codegen --features schema -- bindings"
 codegen-website = "run -p xtask_codegen --features website -- website"
-lintdoc = "run -p xtask_lintdoc --"
+contributors = "run -p xtask_contributors --"
+coverage = "run -p xtask_coverage --profile=release-with-debug --"
 documentation = """
     doc \
     -p rome_*formatter \
@@ -27,13 +29,11 @@ documentation = """
     -p rome_rowan
     --no-deps
 """
-bench_parser = "run -p xtask_bench --release -- --feature parser"
-bench_formatter = "run -p xtask_bench --release -- --feature formatter"
-bench_analyzer = "run -p xtask_bench --release -- --feature analyzer"
-coverage = "run -p xtask_coverage --profile=release-with-debug --"
+format = "fmt --all --verbose"
+lint = "clippy --workspace --all-targets --verbose -- --deny warnings -W clippy::cargo -W clippy::dbg_macro -A clippy::cargo_common_metadata -A clippy::multiple_crate_versions"
+lintdoc = "run -p xtask_lintdoc --"
 rome-cli = "run -p rome_cli --release --"
 rome-cli-dev = "run -p rome_cli --"
-contributors = "run -p xtask_contributors --"
 
 [profile.release]
 lto = true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -22,48 +22,68 @@ Rome can be used via the `rome` bin in the `rome_cli` package:
 cargo run --bin rome -- --help
 ```
 
-Rome can be used as a language server by following the instructions below.
+## Install the required tools
 
-## Testing
+We use [Just](https://just.systems/man/en/) to run scripts or tasks, to make our
+life easier.
 
-To run the tests, just run
+You can install `just` using cargo:
 
 ```shell
-cargo test
+cargo install just
 ```
 
-Or
+But we **highly recommend** to [install it using an OS package manager](https://github.com/casey/just#packages),
+so you won't need to prefix the every command with `cargo`.
+
+Once installed, run the following command install the required tools:
 
 ```shell
-cargo t
+just install-tools
 ```
 
-If you want to test run tests for a single crates, just change path inside the root of the crate you want to test.
-For example, if you want to run the tests of the `rome_cli` crate, you would run:
+And you're good to go hack with Rome and Rust! 🚀
 
-```shell
-cd ./crates/rome_cli
-cargo t
-```
+## Testing
+
+To run the tests, just run
 
-If you to run only the doctests, you would need to pass an argument to the command:
 ```shell
-cargo test --doc
+just test
 ```
 
-In some crates, we use snapshot testing. The majority of snapshot testing is done using [`insta`](https://insta.rs).
+If you want to test the tests for a single crate:
 
-Make sure to install it globally via `cargo`:
+```shell
+just test-crate rome_cli
+```
 
+If you to run only the doctests, you would need to pass an argument to the command:
 ```shell
-cargo install cargo-insta
+jus test-doc
 ```
 
+In some crates, we use snapshot testing. The majority of snapshot testing is done using [`insta`](https://insta.rs).
+`insta` is already installed by the command `just install-tools`.
+
 When a snapshot test fails, you can run:
 - `cargo insta accept` to accept all the changes and update all the snapshots;
 - `cargo insta reject` to reject all the changes;
 - `cargo insta review` to review snapshots singularly;
 
+## Checks
+
+When you finished your work, and you are ready to **commit and open a PR**,
+run the following command:
+
+```shell
+just ready
+```
+
+This command will run the same commands of the CI: format, lint, tests and code generation.
+Eventually everything should be "green" 🟢 and commit all the code that was
+generated.
+
 ## Language Server and VS Code Extension Development
 
 The Rome language server is the binary crate `rome` which can be built using the command:
@@ -147,12 +167,6 @@ pnpm install
 pnpm start
 ```
 
-## Checks
-
-- `cargo lint` is a cargo alias that runs [`clippy`](https://github.com/rust-lang/rust-clippy) - rust official linter - under the hood;
-- `cargo format` is a cargo alias that runs [`rust-fmt`](https://github.com/rust-lang/rustfmt) - rust official formatter - under the hood;
-- `cargo test` will run the suite; make sure to run this command from the root of the project, so it will run the tests of all the internal crates;
-
 ### Generated files
 
 If you work on some parser and you create new nodes or modify existing ones, will need to run a command to update some files that are auto-generated.
@@ -301,45 +315,3 @@ Even minor versions are dedicated to official releases, e.g. `*.6.*`.
 ### Playground
 
 - [run the playground locally](/website/playground/README.md)
-
-### Using just
-
-A lot of the commands above are mor easily accessible using our [Just](https://just.systems/man/en/) recipes. For example:
-
-### Install just
-
-You can install `just` using cargo:
-
-```shell
-cargo install just
-```
-
-Or, using different methods, like explained in their [documentation](https://just.systems/man/en/chapter_4.html).
-
-It's advised to install `just` using a package manager, so
-you can run `just` as a binary.
-
-### Usage
-
-```ignore
-❯ just
-just --list -u
-Available recipes:
-    codegen
-    documentation
-    new-lintrule path name
-    test-lintrule name
-    check-ready
-```
-
-All the necessary `codegen` can be called using
-
-```shell
-just codegen
-```
-
-After all changes are done, the code can be checked if is ready to be pushed with
-
-```shell
-just check-ready
-```
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,88 +1,88 @@
 [workspace]
 # Use the newer version of the cargo resolver
 # https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions
-resolver = "2"
 members = [
-	"crates/*",
-	"xtask/bench",
-	"xtask/codegen",
-	"xtask/coverage",
-	"xtask/lintdoc",
-	"xtask/libs_bench",
-	"xtask/contributors",
+  "crates/*",
+  "xtask/bench",
+  "xtask/codegen",
+  "xtask/coverage",
+  "xtask/lintdoc",
+  "xtask/libs_bench",
+  "xtask/contributors",
 ]
+resolver = "2"
 
 [workspace.package]
-edition = "2021"
-authors = ["Rome Tools Developers and Contributors"]
-license = "MIT"
+authors    = ["Rome Tools Developers and Contributors"]
+edition    = "2021"
+homepage   = "https://rome.tools"
+license    = "MIT"
 repository = "https://github.com/rome/tools"
-homepage = "https://rome.tools"
 
 [profile.release-with-debug]
+debug    = true
 inherits = "release"
-debug = true
 
 [workspace.dependencies]
-indexmap = "1.9.1"
-tracing = { version = "0.1.31", default-features = false, features = ["std"] }
-dashmap = "5.4.0"
+countme    = "3.0.1"
+dashmap    = "5.4.0"
+indexmap   = "1.9.1"
 rustc-hash = "1.1.0"
-countme = "3.0.1"
+tracing    = { version = "0.1.31", default-features = false, features = ["std"] }
 # pinning to version 1.18 to avoid multiple versions of windows-sys as dependency
-tokio = { version = "~1.18.5" }
-insta = "1.21.2"
-quote = { version = "1.0.21" }
-lazy_static = "1.4.0"
-bpaf = { version = "0.8.0", features = ["derive"] }
-bitflags = "2.2.1"
-rome_rowan = { version = "0.0.1", path = "./crates/rome_rowan" }
-rome_console = { version = "0.0.1", path = "./crates/rome_console" }
-rome_diagnostics = { version = "0.0.1", path = "./crates/rome_diagnostics" }
-rome_json_parser = { path = "./crates/rome_json_parser" }
-rome_deserialize = { version = "0.0.0", path = "./crates/rome_deserialize" }
-rome_aria_metadata = { path = "./crates/rome_aria_metadata" }
-rome_aria = { path = "./crates/rome_aria" }
-rome_formatter = { version = "0.0.1", path = "./crates/rome_formatter" }
-rome_service = { path = "./crates/rome_service" }
-rome_flags = { path = "./crates/rome_flags" }
-rome_fs = { path = "./crates/rome_fs" }
-rome_text_edit = { version = "0.0.1", path = "./crates/rome_text_edit" }
-rome_lsp = { path = "./crates/rome_lsp" }
-rome_text_size = { version = "0.0.1", path = "./crates/rome_text_size" }
-rome_json_formatter = { path = "./crates/rome_json_formatter" }
-rome_json_syntax = { version = "0.0.1", path = "./crates/rome_json_syntax" }
-rome_migrate = { path = "./crates/rome_migrate" }
-rome_js_formatter = { path = "./crates/rome_js_formatter" }
-rome_markup = { version = "0.0.1", path = "./crates/rome_markup" }
-rome_css_syntax = { path = "./crates/rome_css_syntax" }
-rome_diagnostics_macros = { version = "0.0.1", path = "./crates/rome_diagnostics_macros" }
+bitflags                    = "2.2.1"
+bpaf                        = { version = "0.8.0", features = ["derive"] }
+insta                       = "1.21.2"
+lazy_static                 = "1.4.0"
+quote                       = { version = "1.0.21" }
+rome_analyze                = { path = "./crates/rome_analyze" }
+rome_aria                   = { path = "./crates/rome_aria" }
+rome_aria_metadata          = { path = "./crates/rome_aria_metadata" }
+rome_console                = { version = "0.0.1", path = "./crates/rome_console" }
+rome_control_flow           = { path = "./crates/rome_control_flow" }
+rome_css_syntax             = { path = "./crates/rome_css_syntax" }
+rome_deserialize            = { version = "0.0.0", path = "./crates/rome_deserialize" }
+rome_diagnostics            = { version = "0.0.1", path = "./crates/rome_diagnostics" }
 rome_diagnostics_categories = { version = "0.0.1", path = "./crates/rome_diagnostics_categories" }
-rome_js_parser = { path = "./crates/rome_js_parser" }
-rome_js_syntax = { version = "0.0.2", path = "./crates/rome_js_syntax" }
-rome_js_factory = { version = "0.0.2", path = "./crates/rome_js_factory" }
-rome_parser = { version = "0.0.1", path = "./crates/rome_parser" }
-rome_analyze = { path = "./crates/rome_analyze" }
-rome_control_flow = { path = "./crates/rome_control_flow" }
-rome_js_semantic = { path = "./crates/rome_js_semantic" }
-rome_js_unicode_table = { version = "0.0.1", path = "./crates/rome_js_unicode_table" }
-rome_json_factory = { version = "0.0.1", path = "./crates/rome_json_factory" }
-tests_macros = { path = "./crates/tests_macros" }
-rome_formatter_test = { path = "./crates/rome_formatter_test" }
-rome_js_analyze  = { path = "./crates/rome_js_analyze" }
-rome_json_analyze  = { path = "./crates/rome_json_analyze" }
-schemars = { version = "0.8.10" }
-smallvec = { version = "1.8.0", features = ["union", "const_new"] }
+rome_diagnostics_macros     = { version = "0.0.1", path = "./crates/rome_diagnostics_macros" }
+rome_flags                  = { path = "./crates/rome_flags" }
+rome_formatter              = { version = "0.0.1", path = "./crates/rome_formatter" }
+rome_formatter_test         = { path = "./crates/rome_formatter_test" }
+rome_fs                     = { path = "./crates/rome_fs" }
+rome_js_analyze             = { path = "./crates/rome_js_analyze" }
+rome_js_factory             = { version = "0.0.2", path = "./crates/rome_js_factory" }
+rome_js_formatter           = { path = "./crates/rome_js_formatter" }
+rome_js_parser              = { path = "./crates/rome_js_parser" }
+rome_js_semantic            = { path = "./crates/rome_js_semantic" }
+rome_js_syntax              = { version = "0.0.2", path = "./crates/rome_js_syntax" }
+rome_js_unicode_table       = { version = "0.0.1", path = "./crates/rome_js_unicode_table" }
+rome_json_analyze           = { path = "./crates/rome_json_analyze" }
+rome_json_factory           = { version = "0.0.1", path = "./crates/rome_json_factory" }
+rome_json_formatter         = { path = "./crates/rome_json_formatter" }
+rome_json_parser            = { path = "./crates/rome_json_parser" }
+rome_json_syntax            = { version = "0.0.1", path = "./crates/rome_json_syntax" }
+rome_lsp                    = { path = "./crates/rome_lsp" }
+rome_markup                 = { version = "0.0.1", path = "./crates/rome_markup" }
+rome_migrate                = { path = "./crates/rome_migrate" }
+rome_parser                 = { version = "0.0.1", path = "./crates/rome_parser" }
+rome_rowan                  = { version = "0.0.1", path = "./crates/rome_rowan" }
+rome_service                = { path = "./crates/rome_service" }
+rome_text_edit              = { version = "0.0.1", path = "./crates/rome_text_edit" }
+rome_text_size              = { version = "0.0.1", path = "./crates/rome_text_size" }
+schemars                    = { version = "0.8.10" }
+smallvec                    = { version = "1.8.0", features = ["union", "const_new"] }
+tests_macros                = { path = "./crates/tests_macros" }
+tokio                       = { version = "~1.18.5" }
 
 
 [profile.dev.package.rome_wasm]
+debug     = true
 opt-level = 1
-debug = true
 
 [profile.test.package.rome_wasm]
+debug     = true
 opt-level = 1
-debug = true
 
 [profile.release.package.rome_wasm]
+debug     = false
 opt-level = 3
-debug = false
diff --git a/clippy.toml b/clippy.toml
@@ -1 +1 @@
-allow-dbg-in-tests = true
+allow-dbg-in-tests = true
diff --git a/crates/rome_analyze/CONTRIBUTING.md b/crates/rome_analyze/CONTRIBUTING.md
@@ -296,7 +296,7 @@ Stage and commit your changes:
 To test if everything is ready, run the following command:
 
 ```shell
-> just check-ready
+just ready
 ```
 
 ### Rule configuration

diff --git a/crates/rome_analyze/Cargo.toml b/crates/rome_analyze/Cargo.toml
@@ -1,22 +1,22 @@
 [package]
-name = "rome_analyze"
-version = "0.0.0"
-edition.workspace = true
-authors.workspace = true
+authors.workspace    = true
+edition.workspace    = true
+license.workspace    = true
+name                 = "rome_analyze"
 repository.workspace = true
-license.workspace = true
+version              = "0.0.0"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-rome_rowan = { workspace = true }
-rome_console = { workspace = true }
-rome_diagnostics = { workspace = true }
 bitflags.workspace = true
-rustc-hash = { workspace = true }
-serde = { version = "1.0.136", features = ["derive"] }
-schemars = { version = "0.8.10", optional = true }
-tracing = { workspace = true }
+rome_console       = { workspace = true }
+rome_diagnostics   = { workspace = true }
+rome_rowan         = { workspace = true }
+rustc-hash         = { workspace = true }
+schemars           = { version = "0.8.10", optional = true }
+serde              = { version = "1.0.136", features = ["derive"] }
+tracing            = { workspace = true }
 
 
 [features]

diff --git a/crates/rome_aria/Cargo.toml b/crates/rome_aria/Cargo.toml
@@ -1,10 +1,10 @@
 [package]
-name = "rome_aria"
-version = "0.0.0"
-edition.workspace = true
-authors.workspace = true
+authors.workspace    = true
+edition.workspace    = true
+license.workspace    = true
+name                 = "rome_aria"
 repository.workspace = true
-license.workspace = true
+version              = "0.0.0"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		allow-dbg-in-tests = true
		allow-dbg-in-tests = true