|
| 1 | +# Contributing to the Elasticsearch specification |
| 2 | + |
| 3 | +Hello, and thank you for contributing! |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +## Prepare the environment |
| 8 | + |
| 9 | +For generating the JSON representation and running the validation code you need |
| 10 | +to install and configure Node.js in your development environment. |
| 11 | + |
| 12 | +You can install Node.js with [`nvm`](https://github.com/nvm-sh/nvm): |
| 13 | + |
| 14 | +```sh |
| 15 | +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash |
| 16 | +``` |
| 17 | + |
| 18 | +Once the installation is completed, install Node.js with `nvm`: |
| 19 | + |
| 20 | +```sh |
| 21 | +# this command will install the version configured in .nvmrc |
| 22 | +nvm install |
| 23 | +``` |
| 24 | + |
| 25 | +From here, you can install the dependencies with `make setup`: |
| 26 | + |
| 27 | +```sh |
| 28 | +make setup |
| 29 | +``` |
| 30 | + |
| 31 | +## Make your change |
| 32 | + |
| 33 | +Documents under the docs/ directory will help you to change the specification. The most relevant ones are: |
| 34 | + |
| 35 | + * [How to add a new API](docs/add-new-api.md) |
| 36 | + * [Specification structure](docs/specification-structure.md) |
| 37 | + * [Modeling Guide](docs/modeling-guide.md) |
| 38 | + * [Documenting the API specification](docs/doc-comments-guide.md) |
| 39 | + * [Fixing a definition, the complete story](docs/validation-example.md) |
| 40 | + |
| 41 | + |
| 42 | +## Send your pull request |
| 43 | + |
| 44 | +To fix any style issues and generate the outputs (that we store in git), please run: |
| 45 | + |
| 46 | +```sh |
| 47 | +make contrib |
| 48 | +``` |
| 49 | + |
| 50 | +Then, follow those steps: |
| 51 | + |
| 52 | +- Sign the CLA https://www.elastic.co/contributor-agreement/ |
| 53 | +- Tag the relative issue (if any) |
| 54 | +- Explain what your changes are doing |
| 55 | +- 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: |
| 56 | + - If the API is unusable without the change -> every supported version |
| 57 | + - If the API is usable, but fix is on the response side -> every supported version |
| 58 | + - 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 |
| 59 | + |
| 60 | + |
0 commit comments