diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5dff0d4a201..023806a1802 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -17,3 +17,16 @@ ## Test Plan + +## Documentation + + + +- [ ] The PR requires documentation +- [ ] I will create a new PR to update the documentation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eacba164734..fc185be86c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -175,6 +175,20 @@ test(lint): add more cases to handle invalid rules When creating a new pull request, it's preferable to use a conventional commit-formatted title, as this title will be used as the default commit message on the squashed commit after merging. +Please use the template provided. + +#### Documentation + +If your PR requires some update on the website (new features, breaking changes, etc.), you should create a new PR once the previous PR is successfully merged. + +Go to the issues section and check the pinned issues. +You will find a _**pinned issue**_ that starts with "Documentation and Focus". Inside, you will find the details of: +- the name of the branch where to point the PR that updates the documentation; +- the PR that we will merge when the release is ready; + +If you can't create a new PR, please let the team know. +The template should help to give all the information to the team. + Here are some other scripts that you might find useful. #### If you are a core contributor @@ -220,7 +234,22 @@ the new snapshot tests. ### Using just -A lot of the commands above are mor easily acessible using our Just recipes. For example: +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 diff --git a/crates/rome_analyze/CONTRIBUTING.md b/crates/rome_analyze/CONTRIBUTING.md index 1c16e8ea2e8..f96cd0e750d 100644 --- a/crates/rome_analyze/CONTRIBUTING.md +++ b/crates/rome_analyze/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Analyzer The analyzer is a generic crate aimed to implement a visitor-like infrastructure, where -it's possible to inspect a piece of AST and emit diagnostics or actions based on a +it's possible to inspect a piece of AST and emit diagnostics or actions based on a static check. # Folder structure @@ -11,8 +11,9 @@ is going to be implemented for the JavaScript language (and its super languages) will be implemented inside the `rome_js_analyze` crate. Rules are divided by capabilities: -- `analyzers/` folder contains rules that don't require any particular capabilities; -- `semantic_analyzer/` folder contains rules that require the use of the semantic model; +- `analyzers/` folder contains rules that don't require any particular capabilities, via the `Ast<>` query type; +- `semantic_analyzer/` folder contains rules that require the use of the semantic model, via `Semantic<>` query type; +- `aria_analyzers/` folder contains rules that require the use ARIA metadata, via `Aria<>` query type; - `assists/` folder contains rules that contribute to refactor code, with not associated diagnostics; these are rules that are usually meant for editors/IDEs; @@ -52,10 +53,10 @@ inside the `semantic_analyzers` folder 3. from there, use the [`declare_rule`](#declare_rule) macro to create a new type ```rust,ignore use rome_analyze::declare_rule; - + declare_rule! { /// Promotes the use of awesome tricks - /// + /// /// ## Examples /// /// ### Invalid @@ -72,25 +73,23 @@ inside the `semantic_analyzers` folder use rome_analyze::{Rule, RuleCategory}; use rome_js_syntax::JsAnyExpression; use rome_analyze::context::RuleContext; - + impl Rule for UseAwesomeTricks { - const CATEGORY: RuleCategory = RuleCategory::Lint; type Query = Semantic; type State = String; type Signals = Option; type Options = (); - + fn run(ctx: &RuleContext) -> Self::Signals {} } ``` -5. the const `CATEGORY` must be `RuleCategory::Lint` otherwise it won't work -6. the `Query` needs to have the `Semantic` type, because we want to have access to the semantic model. -`Query` tells the engine on which AST node we want to trigger the rule. -7. The `State` type doesn't have to be used, so it can be considered optional, but it has +5. the `Query` needs to have the `Semantic` type, because we want to have access to the semantic model. +`Query` tells the engine on which AST node we want to trigger the rule. +6. The `State` type doesn't have to be used, so it can be considered optional, but it has be defined as `type State = ()` -8. The `run` function must be implemented. This function is called every time the analyzer +7. The `run` function must be implemented. This function is called every time the analyzer finds a match for the query specified by the rule, and may return zero or more "signals". -9. Implement the optional `diagnostic` function, to tell the user where's the error and why: +8. Implement the optional `diagnostic` function, to tell the user where's the error and why: ```rust,ignore impl Rule for UseAwesomeTricks { // .. code @@ -99,11 +98,11 @@ finds a match for the query specified by the rule, and may return zero or more " ``` While implementing the diagnostic, please keep [Rome's technical principals](https://rome.tools/#technical) in mind. This function is called of every signal emitted by the `run` function, and it may return - zero or one diagnostic. + zero or one diagnostic. You will have to manually update the file `rome_diagnostics_categories/src/categories.rs` and add a new category for the new rule you're about to create. -10. Implement the optional `action` function, if we are able to provide automatic code fix to the rule: +9. Implement the optional `action` function, if we are able to provide automatic code fix to the rule: ```rust,ignore impl Rule for UseAwesomeTricks { // .. code @@ -225,9 +224,9 @@ declare_rule! { use rome_analyze::declare_rule; declare_rule! { /// Disallow the use of `var` - /// + /// /// ### Invalid - /// + /// /// ```js,expect_diagnostic /// var a, b; /// ``` @@ -255,9 +254,9 @@ use rome_analyze::declare_rule; declare_rule! { /// Disallow the use of `var` - /// + /// /// ### Invalid - /// + /// /// ```js,expect_diagnostic /// var a, b; /// ``` @@ -409,4 +408,4 @@ And at the end, to test our commits are ready to be push we can call > just check-ready ``` -For more details on the available automations, look at our `justfile` at the root of the repository. \ No newline at end of file +For more details on the available automations, look at our `justfile` at the root of the repository. diff --git a/justfile b/justfile index 2c5fa17c193..da01c08c5e2 100644 --- a/justfile +++ b/justfile @@ -1,12 +1,12 @@ _default: just --list -u - + codegen: cargo codegen all cargo codegen-configuration cargo codegen-schema cargo codegen-bindings - + documentation: cargo lintdoc cargo documentation