|
| 1 | +# Contributing to the Elasticsearch Node.js client |
| 2 | + |
| 3 | +The Elasticsearch Node.js client is open source and we love to receive contributions from our community — you! |
| 4 | + |
| 5 | +There are many ways to contribute, |
| 6 | +from writing tutorials or blog posts, |
| 7 | +improving the documentation, |
| 8 | +submitting bug reports and feature requests or writing code. |
| 9 | + |
| 10 | +## Repository structure |
| 11 | +The `master` branch is considered unstable, and it's compatible with Elasticsearch master. Unless you are patching an issue, new features should always be sent to the `master` branch, in case of a bugfix, it depends if the bug affects all the release lines.<br/> |
| 12 | +There is a branch for every supported release line, such as `7.x` or `6.x`. We release bugfixes as soon as possible, while minor and major releases are published at the same time of the Elastic Stack. |
| 13 | + |
| 14 | +Usually for every release line there will be a *published* version and a *next* version. Eg: the `7.x` branch contains the version published on npm, and bugfixes should be sent there, while `7.2` *(assuming that 7.1.x is released)* contains the next version, and new features should be sent there. |
| 15 | + |
| 16 | +## Code contributions |
| 17 | + |
| 18 | +If you have a bugfix or new feature that you would like to contribute, |
| 19 | +please find or open an issue about it first. |
| 20 | +Talk about what you would like to do. |
| 21 | +It may be that somebody is already working on it, |
| 22 | +or that there are particular issues that you should know about before implementing the change. |
| 23 | + |
| 24 | +Note that we strictly follow the [Elastic EOL schedule](https://www.elastic.co/support/eol). |
| 25 | + |
| 26 | +### Submitting your changes |
| 27 | + |
| 28 | +Generally, we require that you test any code you are adding or modifying. |
| 29 | +Once your changes are ready to submit for review: |
| 30 | + |
| 31 | +1. Test your changes |
| 32 | + |
| 33 | + Run the test suite to make sure that nothing is broken. |
| 34 | + Usually run `npm test` is enough, our CI will take care of running the integration test. |
| 35 | + If you want to run them on your own, you should spin up and Elasticsearch instance via the scripts that you |
| 36 | + can find inside the `scripts` folder, and then run `npm run test:integration`.<br/> |
| 37 | + If you want to run the integration test for the Elastic licensed APIs, you should run the `platinum` script, and |
| 38 | + then run `TEST_ES_SERVER=https://elastic:changeme@localhost:9200 npm run test:integration`. |
| 39 | + |
| 40 | +2. Submit a pull request |
| 41 | + |
| 42 | + Push your local changes to your forked copy of the repository and [submit a pull request](https://help.github.com/articles/using-pull-requests). |
| 43 | + In the pull request, |
| 44 | + choose a title which sums up the changes that you have made, |
| 45 | + and in the body provide more details about what your changes do. |
| 46 | + Also mention the number of the issue where discussion has taken place, |
| 47 | + eg "Closes #123". |
| 48 | + |
| 49 | +3. Sign the Contributor License Agreement |
| 50 | + |
| 51 | + Please make sure you have signed our [Contributor License Agreement](https://www.elastic.co/contributor-agreement/). |
| 52 | + We are not asking you to assign copyright to us, |
| 53 | + but to give us the right to distribute your code without restriction. |
| 54 | + We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. |
| 55 | + You only need to sign the CLA once. |
| 56 | + |
| 57 | +4. Be patient |
| 58 | + |
| 59 | + We might not be able to review your code as fast as we would like to, |
| 60 | + but we'll do our best to dedicate it the attention it deserves. |
| 61 | + Your effort is much appreciated! |
| 62 | + |
| 63 | +### Releasing |
| 64 | + |
| 65 | +If you have access to make releases, the process is as follows: |
| 66 | + |
| 67 | +1. Update the version in `package.json` according to the scale of the change. (major, minor or patch) |
| 68 | +1. Commit changes with message `Bumped vx.y.z` where `x.y.z` is the version in `package.json` |
| 69 | +1. Create a release via the GitHub UI. |
| 70 | +1. Wait for CI to finish running the test. |
| 71 | +1. Publish to npm with `npm publish` *(see [publish](https://docs.npmjs.com/cli/publish) and [dist-tag](https://docs.npmjs.com/cli/dist-tag) docs)* |
0 commit comments