From cab3ccbfa89c086ae12cddf860e631bf991501a1 Mon Sep 17 00:00:00 2001
From: Quentin Pradet <quentin.pradet@elastic.co>
Date: Fri, 28 Mar 2025 22:35:30 +0400
Subject: [PATCH] Move contributing instructions to CONTRIBUTING.md (#3959)

(cherry picked from commit 509f88ad09a267354d02bf5f9e960503fa9236b7)
---
 .github/PULL_REQUEST_TEMPLATE.md | 19 +---------
 CONTRIBUTING.md                  | 60 ++++++++++++++++++++++++++++++++
 README.md                        |  4 +++
 3 files changed, 65 insertions(+), 18 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index a1d197cd2a..c1b996510e 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,18 +1 @@
-<!--
-
-Hello there!
-
-Thank you for opening a pull request!
-Please make sure to follow the steps below when opening a pr:
-
-- Sign the CLA https://www.elastic.co/contributor-agreement/
-- Tag the relative issue (if any) and give a brief explanation on what your changes are doing
-- If you did a spec change, remember to generate again the outputs, you can do it by running `make contrib`
-- Add the appropriate backport labels. If you need to backport a breaking change (e.g. changing the structure of a type or changing the type/optionality of a field), please follow these rules:
-  - If the API is unusable without the change -> every supported version
-  - If the API is usable, but fix is on the response side -> every supported version
-  - If the API is usable, but fix is on the request side -> no backport, unless the API is _partially_ usable and the fix unlocks a missing feature that has no workaround
-
-Happy coding!
-
--->
+<!-- Hello there! Thank you for opening a pull request. See CONTRIBUTING.md for instructions. -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..2a4fa56d77
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,60 @@
+# Contributing to the Elasticsearch specification
+
+Hello, and thank you for contributing!
+
+There are many ways to contribute, including opening new issues, improving the docs or fixing typos. However, the instructions below focus on changes to the specification itself.
+
+## Prepare the environment
+
+For generating the JSON representation and running the validation code you need
+to install and configure Node.js in your development environment.
+
+You can install Node.js with [`nvm`](https://github.com/nvm-sh/nvm):
+
+```sh
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+```
+
+Once the installation is completed, install Node.js with `nvm`:
+
+```sh
+# this command will install the version configured in .nvmrc
+nvm install
+```
+
+From here, you can install the dependencies with `make setup`:
+
+```sh
+make setup
+```
+
+## Make your change
+
+Documents under the docs/ directory will help you to change the specification. The most relevant ones are:
+
+ * [How to add a new API](docs/add-new-api.md)
+ * [Specification structure](docs/specification-structure.md)
+ * [Modeling Guide](docs/modeling-guide.md)
+ * [Documenting the API specification](docs/doc-comments-guide.md)
+ * [Fixing a definition, the complete story](docs/validation-example.md)
+
+
+## Send your pull request
+
+To fix any style issues and generate the outputs (that we store in git), please run:
+
+```sh
+make contrib
+```
+
+Then, follow those steps:
+
+- Sign the CLA https://www.elastic.co/contributor-agreement/
+- Tag the relative issue (if any)
+- Explain what your changes are doing
+- Add the appropriate backport labels. If you need to backport a breaking change (e.g. changing the structure of a type or changing the type/optionality of a field), please follow these rules:
+  - If the API is unusable without the change -> every supported version
+  - If the API is usable, but fix is on the response side -> every supported version
+  - If the API is usable, but fix is on the request side -> no backport, unless the API is _partially_ usable and the fix unlocks a missing feature that has no workaround
+
+
diff --git a/README.md b/README.md
index 9cdbab23c9..6e8c85f275 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,10 @@ $ make overlay-docs
 # The generated output can be found in ./output/openapi/
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
+
 ## Make Targets
 
 ```