chore: update contribution guidelines (#3996)

ematipico · web-flow · commit f349182c0e84 · 2022-12-13T09:29:25.000Z
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -17,3 +17,16 @@
 ## Test Plan
 
 <!-- Demonstrate the code is solid. Example: The exact commands you ran and their output. -->
+
+## Documentation
+
+<!--
+
+Read the following paragraph for more information: https://github.com/rome/tools/blob/main/CONTRIBUTING.md#documentation
+
+Tick the checkboxes if your PR requires some documentation, and if you will follow up with that
+
+-->
+
+- [ ] The PR requires documentation
+- [ ] I will create a new PR to update the documentation
diff --git 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
@@ -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<JsAnyExpression>;
         type State = String;
         type Signals = Option<Self::State>;
         type Options = ();
-   
+
         fn run(ctx: &RuleContext<Self>) -> 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.
+For more details on the available automations, look at our `justfile` at the root of the repository.
diff --git 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
