update readme file

CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+We welcome contributions to this repo! Please fork and make a pull request.

README.md

@@ -1,13 +1,17 @@
-# ast-grep-essentials
+# AST-GREP Essentials
 
 ## Overview
 
-ast-grep-essentials, a package designed to enhance the security of your codebase through ast-grep rules. This package
-provides essential security rules, utilities, and tests to help you identify and mitigate potential vulnerabilities in
-your code.
+`ast-grep-essentials` is a collection of
+[`ast-grep`](https://ast-grep.github.io) rules to help you mitigate security
+vulnerabilities and enforce best practices in your code.
 
-> Please read the coderabbit [documentation](https://docs.coderabbit.ai/guides/review-instructions) to understand how to
-> use ast-grep in coderabbit reviews.
+> [!TIP]
+>
+> Please read the CodeRabbit
+> [documentation](https://docs.coderabbit.ai/guides/review-instructions) to
+> understand how to use `ast-grep` in [CodeRabbit](https://coderabbit.ai)
+> reviews.
 
 ## Structure
 
@@ -42,43 +46,65 @@ ast-grep-essentials
 
 The package is organized into three main directories:
 
-- **rules:** Contains ast-grep rules categorized by language and security category.
-- **utils:** Houses utility configs to support rule management.
-- **tests:** Includes test cases for validating the effectiveness of the rules across different languages.
+- `rules`: Contains `ast-grep` rules categorized by language and security
+  category.
+- `utils`: Houses utility configs to support rule management.
+- `tests`: Includes test cases for validating the effectiveness of the rules
+  across different languages.
 
 ### Rules Structure
 
-Within the rules directory, you'll find the following structure:
+Within the `rules` directory, you'll find the following structure:
 
-- **language:** Each language supported by ast-grep (e.g., Python, JavaScript).
-- **category:** Rules categorized based on security concerns (e.g., Input Validation, Authentication).
+- `language`: Each language supported by `ast-grep` (e.g., Python, JavaScript).
+- `category`: Rules categorized based on security concerns (e.g., Input
+  Validation, Authentication).
 
-#### Rule file
+#### Rule file structure
+
+> [!TIP]
+>
+> Read the `ast-grep` > documentation to understand the
+> [rule configuration](https://ast-grep.github.io/reference/yaml.html) and the
+> [rule object properties](https://ast-grep.github.io/reference/rule.html).
 
 Each rule file should have the following structure:
 
 ```yaml
-# unique across the package, not just the language
+# Unique across the package, not just the language
 id: rule-id
-# the language property that the rule is going to get matched against
-language: "language" # e.g., javascript, go
-# the message property is going to get used on the review process and it's important to be clear on what the rule match means.
+# The language property that the rule is going to get matched against
+language: "language" # e.g., javaScript, go
+# A short description of the rule
 message: "Rule message"
-# the note property is going to get used on the review process and it's important to contain as much side meaningful information as possible.
+# A more detailed explanation of the rule
 note: "Rule note"
-# severity level of the rule (e.g., hint, warning) "error" is also valid but is not going to get approved.
+# Severity level of the rule (e.g., hint, warning)
 severity: "severity"
-# ast-grep rule property, check coderabbiit documentation for more information
-rule:
-  ...
+# ast-grep rule property, check documentation for more information
+rule: ...
 ```
 
 ### Tests Structure
 
-Inside the tests directory, tests are organized by language:
+Inside the `tests` directory, tests are organized by language:
+
+- `language`: Test cases specific to the corresponding language's rules.
+- `rule-file`: each test rule file should have by convention the
+  `rule-file-name-test.yml` format.
+
+> [!NOTE]
+>
+> Tests should follow the `ast-grep` testing rules format. Please refer to the
+> `ast-grep` >
+> [documentation](https://ast-grep.github.io/guide/test-rule.html#test-case-configuration)
+
+## Contributing
+
+This project relies on the community to contribute rules. Please open a pull
+request with your rules and tests. Please ensure that the rules are truly
+essential and have a low false positive rate.
 
-- **language:** Test cases specific to the corresponding language's rules.
-- **rule-file:** each test rule file should have by convention the rule-file-name-test.yml
+## Community
 
-> Writing tests should follow the ast-grep testing rules format. Please refer to the
-> ast-grep [documentation](https://ast-grep.github.io/guide/test-rule.html#test-case-configuration)
+Join the discussion on our [Discord server](https://discord.gg/C3rGCxHn).