From 6e8cc250860b81af3b132626ffe76799675e693b Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Fri, 14 Mar 2025 11:30:30 +0400 Subject: [PATCH 1/2] Move contributing instructions to CONTRIBUTING.md --- .github/PULL_REQUEST_TEMPLATE.md | 18 ---------- CONTRIBUTING.md | 60 ++++++++++++++++++++++++++++++++ README.md | 4 +++ 3 files changed, 64 insertions(+), 18 deletions(-) delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index a1d197cd2a..0000000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,18 +0,0 @@ - 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 805924d4fb..9d883fa3b4 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 ``` From 26a6bc76bae1ae1ced53e4bab58cbba2757f6d7b Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Fri, 28 Mar 2025 22:27:53 +0400 Subject: [PATCH 2/2] Mention CONTRIBUTING.md in PULL_REQUEST_TEMPLATE --- .github/PULL_REQUEST_TEMPLATE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..c1b996510e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1 @@ +