CONTRIBUTING.md: add a section about including patches update-contributing-guide

1 files changed, 45 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f318f19ead391..d0c86dc84f528 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -61,6 +61,51 @@ Pull requests should not be squash merged in order to keep complete commit messa
 This means that, when addressing review comments in order to keep the pull request in an always mergeable status, you will sometimes need to rewrite your branch's history and then force-push it with `git push --force-with-lease`.
 Useful git commands that can help a lot with this are `git commit --patch --amend` and `git rebase --interactive`. For more details consult the git man pages or online resources like [git-rebase.io](https://git-rebase.io/) or [The Pro Git Book](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History).
 
+## Including patches
+
+While we do accept custom patches, we strongly encourage submitting patches
+upstream whenever possible. This practice means submitting the patches against
+the original software's repository, which has the potential to benefit the
+broader user community.
+
+For out-of-tree patches fetched using `fetchpatch`, avoid linking to GitHub pull
+requests, as these are mutable and can change with each new commit or
+force-push. Instead, use direct links to specific commit patches such as
+`https://github.com/owner/repo/pull/number/commits/sha.patch`. This ensures that
+the reference to your patch remains constant and accurate.
+
+For consistency and to streamline our patch management process, we recommend
+using `git format-patch` for formatting all patches. This will create a patch
+file that includes the commit message and the associated metadata along with the
+changes themselves. Remember, a well-structured patch is as critical as the code
+changes it contains.
+
+As part of our ongoing efforts to ensure the clarity, maintainability, and
+quality of our source code, we've implemented a policy that requires all
+contributors to provide explanatory comments with every patch submission.
+
+This means that each time you add a patch to the source code, it is mandatory to
+accompany it with a comment that clearly outlines its purpose, regardless of its
+filename or the description inside the patch itself.
+
+This comment should address the following points:
+
+1. **Problem Identification:** What issue or bug does the patch resolve? Or, if
+   it's an enhancement, what does it improve? Please be precise and specific.
+
+2. **Solution Explanation:** How does your patch address the problem identified?
+   Briefly outline the logic or method used to tackle the issue. Remember, the
+   goal is to enable any other contributor to understand your thought process.
+
+3. **Impact Assessment:** Detail the areas of the codebase that may be impacted
+   by this patch. Are there any potential side effects or changes in behavior
+   that other contributors should be aware of?
+
+Implementing this policy not only promotes a more transparent and collaborative
+environment, but it also helps us all to understand the functionality and
+changes within our codebase better. Additionally, it's invaluable for future
+troubleshooting and for the ongoing development of our project.
+
 ## Testing changes
 
 To run the main types of tests locally: