From bf18ac0ab028a522525c6f1c4d9ae37c611156ef Mon Sep 17 00:00:00 2001
From: Marco Pasqualetti <24919330+marcalexiei@users.noreply.github.com>
Date: Tue, 28 Jan 2025 18:53:31 +0100
Subject: [PATCH] docs: add notes about pull request and validating changes
 (#427)

---
 .github/pull_request_template.md              | 20 ++++++--
 .../contributing/local-development.mdx        | 48 +++++++++++++++++++
 .../contributing/pull-requests.mdx            | 30 ++++++++++--
 3 files changed, 90 insertions(+), 8 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 12fac99e..c5a464fe 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,14 +1,24 @@
-## Context & Description
+<!--
+👋 Thank you for your Pull Request 🙏
+-->
+
+### Checklist
+
+- [ ] I have read [Contributing > Pull requests](https://tuono.dev/documentation/contributing/pull-requests)
+
+### Related issue
+
+Fixes #0
+
+<!-- Replace the content with "None" if you haven't an issue to link -->
+
+### Overview
 
 <!--
-Thank you for your Pull Request.
 
 Explain the context and why you're making that change.
 What is the problem you're trying to solve?
 If a new feature is being added,
 describe the intended use case that feature fulfills.
 
-Bug fixes and new features should include tests.
-
-PR guide: https://tuono.dev/documentation/contributing/pull-requests
 -->
diff --git a/apps/documentation/src/routes/documentation/contributing/local-development.mdx b/apps/documentation/src/routes/documentation/contributing/local-development.mdx
index 1775ccc2..e07c483c 100644
--- a/apps/documentation/src/routes/documentation/contributing/local-development.mdx
+++ b/apps/documentation/src/routes/documentation/contributing/local-development.mdx
@@ -158,6 +158,54 @@ docker exec -it tuono-source-container /bin/bash
 > On the documentation remember that `tuono` `npm` package is installed from the registry and
 > it is not linked to the repository.
 
+## Validate your changes
+
+The following checks are all run on pull requests automatically.
+
+You can also perform them locally.
+
+## Formatting
+
+For the typescript part you can run:
+
+```sh
+pnpm run format:check && pnpm run -w repo:root:format:check
+```
+
+For the rust codebase run:
+
+```sh
+cargo fmt
+```
+
+### Linting
+
+For the typescript part you can run:
+
+```sh
+pnpm run lint
+```
+
+For the rust codebase run:
+
+```sh
+cargo clippy -- -D warnings
+```
+
+### Tests
+
+For the typescript part you can run:
+
+```sh
+pnpm run test
+```
+
+For the rust codebase run:
+
+```sh
+cargo test
+```
+
 import NavigationButtons from '../../../components/NavigationButtons'
 
 <NavigationButtons
diff --git a/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx b/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx
index 6d1b02c4..ec9d089b 100644
--- a/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx
+++ b/apps/documentation/src/routes/documentation/contributing/pull-requests.mdx
@@ -24,10 +24,22 @@ you can check the [official documentation](https://docs.github.com/en/pull-reque
 
 ---
 
-- If you are fixing an issue, bear in mind to link the issue itself in the PR description.
-- If you are adding a new feature, describe the intended use case that the feature fulfills.
+- Please do:
 
-> Bug fixes and new features should include tests.
+  - Fill the template in full
+
+    - If you are fixing an issue, bear in mind to link the issue itself in the PR description.
+    - If you are adding a new feature, describe the intended use case that the feature fulfills.
+
+  - Ensure your code is valid by running the test on you local machine.
+    Refer to ["Validate your changes" section](/documentation/contributing/local-development)
+
+- Please **don't**:
+
+  - Do not use force push after marking the PR ready for review.
+
+    **Reasoning:** GitHub cannot track changes across force pushes,
+    which slows down our ability to perform incremental reviews.
 
 ## Title
 
@@ -76,6 +88,18 @@ E.g.: `fix(crates/tuono): remove cargo warnings`
 A succinct title for the PR.
 (The title max length is set to 100 characters)
 
+## Addressing review feedback
+
+Once we've reviewed your PR, we’ll provide feedback on any changes that need attention.
+If you feel a suggested change isn’t correct, feel free to discuss it with us in the comments.
+
+Please [post your comments](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-comments-to-a-pull-request)
+as line comments when possible so they can be threaded.
+
+After addressing all feedback, whether through code changes or by starting a follow-up discussion,
+please [re-request a review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#re-requesting-a-review)
+from each maintainer whose feedback you've addressed.
+
 import NavigationButtons from '../../../components/NavigationButtons'
 
 <NavigationButtons