docs: update README content, add rules docs

- docs: add CONTRIBUTING Guide content
- docs: add output instructions format

CONTRIBUTING.md

@@ -1,5 +1,116 @@
 # Contributing Guide
 
+By following these guidelines, you'll contribute effectively to our project, ensuring code quality, maintainability, and seamless collaboration.
+
+If you want to contribute to _Shared GitHub DangerJS_ project, here's what you need to know:
+
+-   [Contributing Guide](#contributing-guide)
+    -   [Code and Testing](#code-and-testing)
+    -   [Guidelines and Best Practices](#guidelines-and-best-practices)
+    -   [Documentation and Maintenance](#documentation-and-maintenance)
+    -   [Tools and Extensions](#tools-and-extensions)
+    -   [Local Testing](#local-testing)
+
+## Code and Testing
+
+-   **Code Style and Structure:**
+
+    -   **Pre-Commit Hooks:** Install pre-commit hooks in this repository using the `pre-commit install` command.
+
+    -   **Readable Code Structure:** Structure your code in a readable manner. The main logic should be in the default rule function, with implementation details in helper functions. Avoid nested `if` statements and unnecessary `else` statements to maintain code clarity and simplicity.
+
+    -   **Remove Debug Statements:** Remove any debug statements (e.g., `console.log`) from your rules.
+
+    -   **Handling Rule Exit Points:** All exit points from the rule must be handled by `recordRuleExitStatus` function. Expected outputs are `Passed`, `Failed`, `Passed (with suggestions)`, or `Skipped (<optional text>)`.
+
+    -   **Environment Variables:** For any new rule, add all necessary environment variables to the `action.yml` file's variables section and `src/configParameters.ts`. Ensure these are properly described in the documentation.
+
+    -   **Rule Output Formatting:** If your rule produces output that is formatted in a more complicated way (e.g., nesting, output from loops), test the final output in a test project. Include a thumbnail of its appearance in your pull request (PR) for clearer understanding and review.
+
+-   **Code Formatting and Linting:**
+
+    -   **Prettier and ESLint:** This project uses `Prettier` for code formatting and `ESLint` for linting. These checks will run as part of the pre-commit hooks and the CI pipeline.
+
+    -   **IDE Extensions:** It is recommended for developers to install `Prettier` and `ESLint` extensions in your IDE (typically VS Code) to ensure code consistency.
+
+-   **Creating New DangerJS rules:**
+
+    -   When creating a new DangerJS rule, ensure it includes thorough tests. Reference existing rules for guidance.
+
+    -   Consider whether the new rule is universally applicable across all Espressif projects.
+
+    -   If it's specific to a single project or a small group of projects, the rule should be disabled by default.
+
+-   **Updating Existing Danger Rules:** When updating an existing Danger rule, ensure new features or behavioral changes are covered by additional tests.
+
+-   **Automated Tests:** Each Danger rule (e.g. `src/rulePrSize.ts`) must have an automated test in test directory (e.g. `tests/rulePrSize.test.ts`). We aim for full test coverage, so **partial tests will not be accepted**. The tests should cover all typical usage scenarios as well as edge cases to ensure robustness.
+
+-   **Testing Tool:** We use the npm module `jest` for testing. It is recommended to run `npm test` frequently during development to ensure that all aspects of your code are functioning as expected.
+
+## Guidelines and Best Practices
+
+-   **No Breaking Changes:** Since this project is used as shared CI across many projects, **breaking changes to existing code are strictly prohibited**.
+
+-   **Release Tags:** Though the project uses release tags, most external projects that import this CI reference the `v1` branch.
+
+## Documentation and Maintenance
+
+-   **Changelog:** Update the `CHANGELOG.md` when making changes to the project.
+
+-   **Documentation:** Regularly check and update the documentation to keep it current.
+
+    -   **Rule Descriptions:** Each Danger rule should have a description in the documentation. This should include what the rule does, its usefulness, any configurable parameters, and examples of both good and bad outputs.
+    -   **PR Descriptions and Documentation:** When contributing, describe all changes or new features in the PR (Pull Request) description as well as in the documentation.
+    -   **Updates to Existing Rules:** When making changes to an existing rule, review the existing documentation to ensure it is up-to-date with the changes.
+
+## Tools and Extensions
+
+-   **Pre-Commit Hooks:** Installing pre-commit (`pip install pre-commit`) and the project's pre-commit hooks (`pre-commit install`) is mandatory. Unformatted code will be not accepted.
+-   **Recommended VS Code Extensions:** These extensions can help your development of this project:
+    -   `streetsidesoftware.code-spell-checker`
+    -   `kisstkondoros.vscode-codemetrics`
+    -   `Orta.vscode-jest`
+    -   `esbenp.prettier-vscode`
+    -   `rvest.vs-code-prettier-eslint`
+
+## Local Testing
+
+Avoid waiting for the GitLab pipeline by testing DangerJS rules locally:
+
+-   **Environment Setup:** Rename `.env.sample` to `.env` and add the GitLab token to `DANGER_GITLAB_API_TOKEN`. Source the env to export all variables to your shell:
+
+    ```sh
+    source .env
+    ```
+
+-   **Installing Dependencies:** Run `npm install` on your local machine to install project dependencies, including dev dependencies such as type checkers and the test framework.
+
+-   **Running DangerJS Locally:** Use command to run DangerJS in your local shell, just like in the CI pipeline:
+
+    ```sh
+    npx danger --dangerfile=src/dangerfile.ts pr <url_of_pull_request>
+    ```
+
+-   **Simplifying Local Testing:**
+
+    -   **Temporary Rule Isolation:** For faster development, you can temporarily comment out other Danger rules in `dangerfile.ts` and retain only the rule you are working on.
+
+    -   **Restoring Dangerfile:** Don’t forget to restore (uncomment) the temporarily suppressed lines in `dangerfile.ts` before pushing your changes.
+
+    -   **Running Specific Tests:** To run a specific test file only, use the command:
+
+        ```sh
+        npx jest tests/<test_file_name>.test.ts
+        ```
+
+        ... for example:
+
+        ```sh
+        npx jest tests/rulePrDescription.test.ts
+        ```
+
+    -   **Monitoring Output:** Pay attention to the terminal output during local testing. This unformatted Markdown output is the equivalent of the feedback message provided by the Danger bot in the actual project PR.
+
 ---
 
 👏**Thank you for your contributions.**

README.md

@@ -1,11 +1,140 @@
-# Shared Danger GitHub
+<div align="center">
+    <img src="docs/espressif-danger.png" width="800"></a>
+    <h1>Espressif Shared GitHub DangerJS</h1>
+    <hr>
+    <!-- Gitlab Badges -->
+    <img alt="Codebase tests (Jest)" src="https://github.com/espressif/shared-github-dangerjs/workflows/Codebase%20tests%20(Jest)/badge.svg" />
+    <hr>
+</div>
 
-This is the DangerJS pull request linter GitHub action, that can be called from another repositories. It's purpose is to keep the style of each PR in the specified style and automatically check for simple things like correct PR description, meaningful git messages, correct PR target branch, etc.
+**Welcome to the DangerJS Pull Request linter!**
 
--TBD-
--TBD-
--TBD-
+This is GitHub action that can be used across different Espressif GitHub repositories and helps make sure that contributors Pull Requests (PRs) follow a specific style.
 
-<!-- BADGES -->
+It checks things like:
 
-![Codebase tests (Jest)](<https://github.com/espressif/shared-github-dangerjs/workflows/Codebase%20tests%20(Jest)/badge.svg>)
+-   sufficient merge request descriptions
+-   meaningful commit messages in conventional commit style
+-   size of changes in MR
+-   simple branch git history
+-   source and target branch
+
+Because DangerJS does this automatically, human reviewers can focus more on code changes and spend their time reviewing PRs more productively.
+
+---
+
+-   [Usage in Your Project](#usage-in-your-project)
+-   [DangerJS rules](#dangerjs-rules)
+-   [UI output](#ui-output)
+-   [Configuration Options](#configuration-options)
+-   [Project issues](#project-issues)
+-   [Contributing](#contributing)
+
+## Usage in Your Project
+
+To integrate DangerJS, add GitHub workflow `.github/workflows/dangerjs.yml` to your project with this content:
+
+<!-- prettier-ignore -->
+```yaml
+name: DangerJS Pull Request linter
+on:
+  pull_request_target:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  pull-requests: write
+  contents: write
+
+jobs:
+  pull-request-style-linter:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out PR head
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+
+    - name: DangerJS pull request linter
+      uses: espressif/shared-github-dangerjs@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+-   **GitHub token** This token is automatically obtained from the GitHub project and its specific permissions are set in the yaml workflow file. Avoid adding unnecessarily high permissions to this token, keep it set as in the example above.
+
+---
+
+**🤝 Quick Integration:** If your goal is to add Shared GitHub DangerJS into your project with the default Espressif settings, **then at this point you're all set!**
+
+For custom configurations, refer to the descriptions of individual rules to learn how to tweak them to your needs.
+
+---
+
+## DangerJS rules
+
+-   [Pull Request sufficient Description](docs/rules/rulePrDescription.md)
+-   [Pull Request Maximum Commits](docs/rules/ruleNumberOfCommits.md)
+-   [Pull Request Commit Messages](docs/rules/ruleCommitMessages.md)
+-   [Pull Request Size](docs/rules/rulePrSize.md)
+-   [Pull Request Source Branch name](docs/rules/ruleSourceBranchName.md)
+-   [Pull Request Target Branch name](docs/rules/ruleTargetBranch.md)
+
+## UI output
+
+-   [BOT comment Output Instructions format](docs/rules/outputInstructions.md)
+
+---
+
+## Configuration Options
+
+If your project has specific needs, Shared GitHub DangerJS can be configured to meet them.
+
+**Here is complete list of configurable parameters:**
+
+| Parameter                                              | CI Variable                            | Type | Default value                                      |
+| ------------------------------------------------------ | -------------------------------------- | ---- | -------------------------------------------------- |
+| Enable rule PR Description                             | `rule-description`                     | str  | `"true"` (use `"false"` to disable this rule)      |
+| Enable rule PR Lint Commit Messages                    | `rule-commit-messages`                 | str  | `"true"` (use `"false"` to disable this rule)      |
+| Enable rule PR Size (changed lines)                    | `rule-size-lines`                      | str  | `"true"` (use `"false"` to disable this rule)      |
+| Enable rule PR Source branch name                      | `rule-source-branch`                   | str  | `"true"` (use `"false"` to disable this rule)      |
+| Enable rule PR Target branch name                      | `rule-target-branch`                   | str  | `"true"` (use `"false"` to disable this rule)      |
+| Enable rule PR Too Many Commits                        | `rule-max-commits`                     | str  | `"true"` (use `"false"` to disable this check)     |
+| Commit message allowed "Type"s                         | `commit-messages-types`                | str  | `"change,ci,docs,feat,fix,refactor,remove,revert"` |
+| Commit message maximum length "Body" line              | `commit-messages-max-body-line-length` | str  | `"100"`                                            |
+| Commit message maximum length "Summary"                | `commit-messages-max-summary-length`   | str  | `"72"`                                             |
+| Commit message minimum length "Summary"                | `commit-messages-min-summary-length`   | str  | `"20"`                                             |
+| Ignore sections of PR description when counting length | `description-ignore-sections`          | str  | `"related,release,breaking"`                       |
+| Maximum changed code lines in PR                       | `max-size-lines`                       | str  | `"1000"`                                           |
+| Maximum commits in PR (soft limit, throw `info`)       | `max-commits-info`                     | str  | `"2"`                                              |
+| Maximum commits in PR (hard limit, throw `warn`)       | `max-commits-warn`                     | str  | `"5"`                                              |
+| Minimum length of PR description                       | `description-min-length`               | str  | `"50"`                                             |
+
+These values can be defined in your project `DangerJS Pull Request linter` workflow, for example like this:
+
+<!-- prettier-ignore -->
+```yaml
+    - name: DangerJS pull request linter
+      uses: espressif/shared-github-dangerjs@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        instructions-contributions-file: 'CONTRIBUTING.md'
+        instructions-cla-link: 'https://cla-assistant.io/espressif/test'
+        instructions-gitlab-mirror: 'true'
+        max-commits-info: '3'
+        max-commits-warn: '6'
+```
+
+See more config options in [DangerJS rules](#dangerjs-rules).
+
+---
+
+## Project issues
+
+If you encounter any issues, feel free to report them in the [project's issues](https://github.com/espressif/shared-github-dangerjs/issues) or create Pull Request with your suggestion.
+
+## Contributing
+
+📘 If you are interested in contributing to this project, see the [project Contributing Guide](CONTRIBUTING.md).
+
+---