Skip to content

[DOCS] Updates CONTRIBUTING #2670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 28, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@ This will run `bundle install` in all subprojects.

You can run the client code right away in a Interactive Ruby Shell by running the following command from the project's root directory:
```
$ ./elasticsearch/bin/elastic_ruby_console
$ rake console # calls ./elasticsearch/bin/elastic_ruby_console
[1] elastic_ruby(main)> client = Elasticsearch::Client.new(host: 'http://elastic:changeme@localhost:9200', log: true)
[2] elastic_ruby(main)> client.info
```

This will use either `irb` or `pry` and load the `elasticsearch` and `elasticsearch-api` gems into the shell.
This will use either `irb` or `pry` and load the `elasticsearch` and `elasticsearch-api` gems into the shell.

# Tests

Expand All @@ -31,8 +31,8 @@ To run the tests, you need to start a testing cluster on port 9200. We suggest u
rake docker:start[VERSION]
```

E.g.: `rake docker:start[8.0-SNAPSHOT]`.
To start the container with Platinum, pass it in as a parameter: `rake docker:start[7.x-SNAPSHOT,platinum]`.
E.g.: `rake docker:start[9.0.0-SNAPSHOT]`.
To start the container with Platinum, pass it in as a parameter: `rake docker:start[8.x-SNAPSHOT,platinum]`.

There's another rake task that will read the STACK_VERSION value from `.buildkite/pipeline.yml` and run that version of Elasticsearch: `rake es:up`.

Expand All @@ -42,6 +42,12 @@ max virtual memory areas vm.max_map_count [65530] likely too low, increase to at
```
Check [this link](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#_set_vm_max_map_count_to_at_least_262144) for instructions on how to fix it.

You can also use [start-local](https://github.com/elastic/start-local), which can run Elasticsearch and Kibana locally for development/testing. You only need to run Elasticsearch (`-esonly`) for development purposes, and you can specify a version with the `-v` parameter:

```bash
curl -fsSL https://elastic.co/start-local | sh -s -- -esonly -v 9.0.0
```

As mentioned, the tests will atempt to run against `http://localhost:9200` by default. We provide the Docker task for the test cluster and recommend using it. But you can provide a different test server of your own. If you're using a different host or port, set the `TEST_ES_SERVER` environment variable with the server information. E.g.:

```
Expand All @@ -51,12 +57,20 @@ $ TEST_ES_SERVER='http://localhost:9250' be rake test:client
To run all the tests in all the subprojects, use the Rake task:

```
time rake test:client
rake test:client
```

# Elasticsearch Rest API YAML Test Runner
# Elasticsearch Rest API Tests

The integration tests on this project run the [Elasticsearch Client tests](https://github.com/elastic/elasticsearch-clients-tests/) with the [Elasticsearch Tests Runner](https://github.com/elastic/es-test-runner-ruby/) library. This runs in CI against an Elasticsearch cluster in Docker. The [Elasticsearch's REST API Spec tests](https://github.com/elastic/elasticsearch/tree/main/rest-api-spec/src/main/resources/rest-api-spec/test#test-suite) can still be ran following [these instructions](https://github.com/elastic/elasticsearch-ruby/tree/main/elasticsearch-api/api-spec-testing#readme).

You can run the yaml API tests with:

```
rake test:yaml
```

See the API Spec tests [README](https://github.com/elastic/elasticsearch-ruby/tree/main/elasticsearch-api/api-spec-testing#readme).
Check `rake -T` for more test tasks.

# Contributing

Expand Down