mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-17 20:05:09 -04:00
Spelling and grammar fixes in repository docs (#102345)
- fixed a few typos - normalized proper names: Gradle, GitHub, Maven, Elasticsearch, Spotless - grammar fixes (commas, etc.) - unified section titles style
This commit is contained in:
sabi0
GitHub
parent
a8bd0b2f42
commit
8713ca82ac
2 changed files with 81 additions and 80 deletions
81
BUILDING.md
81
BUILDING.md
|
|
@ -3,7 +3,7 @@ Building Elasticsearch with Gradle
|
|||
|
||||
Elasticsearch is built using the [Gradle](https://gradle.org/) open source build tools.
|
||||
|
||||
This document provides a general guidelines for using and working on the elasticsearch build logic.
|
||||
This document provides a general guidelines for using and working on the Elasticsearch build logic.
|
||||
|
||||
## Build logic organisation
|
||||
|
||||
|
|
@ -11,56 +11,56 @@ The Elasticsearch project contains 3 build-related projects that are included in
|
|||
|
||||
### `build-conventions`
|
||||
|
||||
This project contains build conventions that are applied to all elasticsearch projects.
|
||||
This project contains build conventions that are applied to all Elasticsearch projects.
|
||||
|
||||
### `build-tools`
|
||||
|
||||
This project contains all build logic that we publish for third party elasticsearch plugin authors.
|
||||
This project contains all build logic that we publish for third party Elasticsearch plugin authors.
|
||||
We provide the following plugins:
|
||||
|
||||
- `elasticsearch.esplugin` - A gradle plugin for building an elasticsearch plugin.
|
||||
- `elasticsearch.testclusters` - A gradle plugin for setting up es clusters for testing within a build.
|
||||
- `elasticsearch.esplugin` - A Gradle plugin for building an elasticsearch plugin.
|
||||
- `elasticsearch.testclusters` - A Gradle plugin for setting up es clusters for testing within a build.
|
||||
|
||||
This project is published as part of the elasticsearch release and accessible by
|
||||
This project is published as part of the Elasticsearch release and accessible by
|
||||
`org.elasticsearch.gradle:build-tools:<versionNumber>`.
|
||||
These build tools are also used by the `elasticsearch-hadoop` project maintained by elastic.
|
||||
|
||||
### `build-tools-internal`
|
||||
|
||||
This project contains all elasticsearch project specific build logic that is not meant to be shared
|
||||
This project contains all Elasticsearch project specific build logic that is not meant to be shared
|
||||
with other internal or external projects.
|
||||
|
||||
## Build guidelines
|
||||
|
||||
This is an intentionally small set of guidelines to build users and authors
|
||||
to ensure we keep the build consistent. We also publish elasticsearch build logic
|
||||
as `build-tools` to be usuable by thirdparty elasticsearch plugin authors. This is
|
||||
to ensure we keep the build consistent. We also publish Elasticsearch build logic
|
||||
as `build-tools` to be usable by thirdparty Elasticsearch plugin authors. This is
|
||||
also used by other elastic teams like `elasticsearch-hadoop`.
|
||||
Breaking changes should therefore be avoided and an appropriate deprecation cycle
|
||||
should be followed.
|
||||
|
||||
### Stay up to date
|
||||
|
||||
The elasticsearch build usually uses the latest Gradle GA release. We stay as close to the
|
||||
The Elasticsearch build usually uses the latest Gradle GA release. We stay as close to the
|
||||
latest Gradle releases as possible. In certain cases an update is blocked by a breaking behaviour
|
||||
in Gradle. We're usually in contact with the gradle team here or working on a fix
|
||||
in Gradle. We're usually in contact with the Gradle team here or working on a fix
|
||||
in our build logic to resolve this.
|
||||
|
||||
**The Elasticsearch build will fail if any deprecated Gradle API is used.**
|
||||
|
||||
### Follow Gradle best practices
|
||||
|
||||
Tony Robalik has compiled a good list of rules that aligns with ours when it comes to writing and maintaining elasticsearch
|
||||
gradle build logic at http://autonomousapps.com/blog/rules-for-gradle-plugin-authors.html.
|
||||
Tony Robalik has compiled a good list of rules that aligns with ours when it comes to writing and maintaining Elasticsearch
|
||||
Gradle build logic at http://autonomousapps.com/blog/rules-for-gradle-plugin-authors.html.
|
||||
Our current build does not yet tick off all those rules everywhere but the ultimate goal is to follow these principles.
|
||||
The reasons for following those rules besides better readability or maintenance are also the goal to support newer gradle
|
||||
The reasons for following those rules besides better readability or maintenance are also the goal to support newer Gradle
|
||||
features that we will benefit from in terms of performance and reliability.
|
||||
E.g. [configuration-cache support](https://github.com/elastic/elasticsearch/issues/57918), [Project Isolation]([https://gradle.github.io/configuration-cache/#project_isolation) or
|
||||
[predictive test selection](https://gradle.com/gradle-enterprise-solutions/predictive-test-selection/)
|
||||
|
||||
### Make a change in the build
|
||||
|
||||
There are a few guidelines to follow that should make your life easier to make changes to the elasticsearch build.
|
||||
There are a few guidelines to follow that should make your life easier to make changes to the Elasticsearch build.
|
||||
Please add a member of the `es-delivery` team as a reviewer if you're making non-trivial changes to the build.
|
||||
|
||||
#### Adding or updating a dependency
|
||||
|
|
@ -93,13 +93,13 @@ We prefer sha256 checksums as md5 and sha1 are not considered safe anymore these
|
|||
will have the `origin` attribute been set to `Generated by Gradle`.
|
||||
|
||||
>A manual confirmation of the Gradle generated checksums is currently not mandatory.
|
||||
>If you want to add a level of verification you can manually confirm the checksum (e.g by looking it up on the website of the library)
|
||||
>If you want to add a level of verification you can manually confirm the checksum (e.g. by looking it up on the website of the library)
|
||||
>Please replace the content of the `origin` attribute by `official site` in that case.
|
||||
>
|
||||
|
||||
#### Custom Plugin and Task implementations
|
||||
#### Custom plugin and task implementations
|
||||
|
||||
Build logic that is used across multiple subprojects should considered to be moved into a Gradle plugin with according Gradle task implmentation.
|
||||
Build logic that is used across multiple subprojects should be considered to be moved into a Gradle plugin with according Gradle task implementation.
|
||||
Elasticsearch specific build logic is located in the `build-tools-internal` subproject including integration tests.
|
||||
|
||||
- Gradle plugins and Tasks should be written in Java
|
||||
|
|
@ -108,7 +108,7 @@ Elasticsearch specific build logic is located in the `build-tools-internal` subp
|
|||
|
||||
#### Declaring tasks
|
||||
|
||||
The elasticsearch build makes use of the [task avoidance API](https://docs.gradle.org/current/userguide/task_configuration_avoidance.html) to keep the configuration time of the build low.
|
||||
The Elasticsearch build makes use of the [task avoidance API](https://docs.gradle.org/current/userguide/task_configuration_avoidance.html) to keep the configuration time of the build low.
|
||||
|
||||
When declaring tasks (in build scripts or custom plugins) this means that we want to _register_ a task like:
|
||||
|
||||
|
|
@ -118,18 +118,18 @@ instead of eagerly _creating_ the task:
|
|||
|
||||
task someTask { ... }
|
||||
|
||||
The major difference between these two syntaxes is, that the configuration block of an registered task will only be executed when the task is actually created due to the build requires that task to run. The configuration block of an eagerly created tasks will be executed immediately.
|
||||
The major difference between these two syntaxes is, that the configuration block of a registered task will only be executed when the task is actually created due to the build requires that task to run. The configuration block of an eagerly created tasks will be executed immediately.
|
||||
|
||||
By actually doing less in the gradle configuration time as only creating tasks that are requested as part of the build and by only running the configurations for those requested tasks, using the task avoidance api contributes a major part in keeping our build fast.
|
||||
By actually doing less in the Gradle configuration time as only creating tasks that are requested as part of the build and by only running the configurations for those requested tasks, using the task avoidance api contributes a major part in keeping our build fast.
|
||||
|
||||
#### Registering test clusters
|
||||
|
||||
When using the elasticsearch test cluster plugin we want to use (similar to the task avoidance API) a Gradle API to create domain objects lazy or only if required by the build.
|
||||
When using the Elasticsearch test cluster plugin we want to use (similar to the task avoidance API) a Gradle API to create domain objects lazy or only if required by the build.
|
||||
Therefore we register test cluster by using the following syntax:
|
||||
|
||||
def someClusterProvider = testClusters.register('someCluster') { ... }
|
||||
|
||||
This registers a potential testCluster named `somecluster` and provides a provider instance, but doesn't create it yet nor configures it. This makes the gradle configuration phase more efficient by
|
||||
This registers a potential testCluster named `somecluster` and provides a provider instance, but doesn't create it yet nor configures it. This makes the Gradle configuration phase more efficient by
|
||||
doing less.
|
||||
|
||||
To wire this registered cluster into a `TestClusterAware` task (e.g. `RestIntegTest`) you can resolve the actual cluster from the provider instance:
|
||||
|
|
@ -139,23 +139,23 @@ To wire this registered cluster into a `TestClusterAware` task (e.g. `RestIntegT
|
|||
nonInputProperties.systemProperty 'tests.leader_host', "${-> someClusterProvider.get().getAllHttpSocketURI().get(0)}"
|
||||
}
|
||||
|
||||
#### Adding additional integration tests
|
||||
#### Adding integration tests
|
||||
|
||||
Additional integration tests for a certain elasticsearch modules that are specific to certain cluster configuration can be declared in a separate so called `qa` subproject of your module.
|
||||
Additional integration tests for a certain Elasticsearch modules that are specific to certain cluster configuration can be declared in a separate so called `qa` subproject of your module.
|
||||
|
||||
The benefit of a dedicated project for these tests are:
|
||||
- `qa` projects are dedicated two specific usecases and easier to maintain
|
||||
- `qa` projects are dedicated two specific use-cases and easier to maintain
|
||||
- It keeps the specific test logic separated from the common test logic.
|
||||
- You can run those tests in parallel to other projects of the build.
|
||||
|
||||
#### Using test fixtures
|
||||
|
||||
Sometimes we want to share test fixtures to setup the code under test across multiple projects. There are basically two ways doing so.
|
||||
Sometimes we want to share test fixtures to set up the code under test across multiple projects. There are basically two ways doing so.
|
||||
|
||||
Ideally we would use the build-in [java-test-fixtures](https://docs.gradle.org/current/userguide/java_testing.html#sec:java_test_fixtures) gradle plugin.
|
||||
Ideally we would use the build-in [java-test-fixtures](https://docs.gradle.org/current/userguide/java_testing.html#sec:java_test_fixtures) Gradle plugin.
|
||||
This plugin relies on having a separate sourceSet for the test fixtures code.
|
||||
|
||||
In the elasticsearch codebase we have test fixtures and actual tests within the same sourceSet. Therefore we introduced the `elasticsearch.internal-test-artifact` plugin to provides another build artifact of your project based on the `test` sourceSet.
|
||||
In the Elasticsearch codebase we have test fixtures and actual tests within the same sourceSet. Therefore we introduced the `elasticsearch.internal-test-artifact` plugin to provides another build artifact of your project based on the `test` sourceSet.
|
||||
|
||||
|
||||
This artifact can be resolved by the consumer project as shown in the example below:
|
||||
|
|
@ -168,9 +168,9 @@ dependencies {
|
|||
```
|
||||
|
||||
This test artifact mechanism makes use of the concept of [component capabilities](https://docs.gradle.org/current/userguide/component_capabilities.html)
|
||||
similar to how the gradle build-in `java-test-fixtures` plugin works.
|
||||
similar to how the Gradle build-in `java-test-fixtures` plugin works.
|
||||
|
||||
`testArtifact` is a shortcut declared in the elasticsearch build. Alternatively you can declare the dependency via
|
||||
`testArtifact` is a shortcut declared in the Elasticsearch build. Alternatively you can declare the dependency via
|
||||
|
||||
```
|
||||
dependencies {
|
||||
|
|
@ -186,7 +186,7 @@ dependencies {
|
|||
|
||||
To test an unreleased development version of a third party dependency you have several options.
|
||||
|
||||
#### How to use a maven based third party dependency via mavenlocal?
|
||||
#### How to use a Maven based third party dependency via `mavenlocal`?
|
||||
|
||||
1. Clone the third party repository locally
|
||||
2. Run `mvn install` to install copy into your `~/.m2/repository` folder.
|
||||
|
|
@ -200,16 +200,15 @@ To test an unreleased development version of a third party dependency you have s
|
|||
}
|
||||
```
|
||||
4. Update the version in your dependency declaration accordingly (likely a snapshot version)
|
||||
5. Run the gradle build as needed
|
||||
5. Run the Gradle build as needed
|
||||
|
||||
#### How to use a maven built based third party dependency with jitpack repository?
|
||||
#### How to use a Maven built based third party dependency with JitPack repository?
|
||||
|
||||
https://jitpack.io is an adhoc repository that supports building maven projects transparently in the background when
|
||||
resolving unreleased snapshots from a github repository. This approach also works as temporally solution
|
||||
https://jitpack.io is an adhoc repository that supports building Maven projects transparently in the background when
|
||||
resolving unreleased snapshots from a GitHub repository. This approach also works as temporally solution
|
||||
and is compliant with our CI builds.
|
||||
|
||||
1. Add the JitPack repository to the root build file:
|
||||
|
||||
```
|
||||
allprojects {
|
||||
repositories {
|
||||
|
|
@ -227,7 +226,7 @@ dependencies {
|
|||
As version you could also use a certain short commit hash or `main-SNAPSHOT`.
|
||||
In addition to snapshot builds JitPack supports building Pull Requests. Simply use PR<NR>-SNAPSHOT as the version.
|
||||
|
||||
3. Run the gradle build as needed. Keep in mind the initial resolution might take a bit longer as this needs to be built
|
||||
3. Run the Gradle build as needed. Keep in mind the initial resolution might take a bit longer as this needs to be built
|
||||
by JitPack in the background before we can resolve the adhoc built dependency.
|
||||
|
||||
---
|
||||
|
|
@ -240,7 +239,7 @@ not want to ship unreleased libraries into our releases.
|
|||
|
||||
#### How to use a custom third party artifact?
|
||||
|
||||
For third party libraries that are not built with maven (e.g. ant) or provided as a plain jar artifact we can leverage
|
||||
For third party libraries that are not built with Maven (e.g. Ant) or provided as a plain jar artifact we can leverage
|
||||
a flat directory repository that resolves artifacts from a flat directory on your filesystem.
|
||||
|
||||
1. Put the jar artifact with the format `artifactName-version.jar` into a directory named `localRepo` (you have to create this manually)
|
||||
|
|
@ -264,7 +263,7 @@ allprojects {
|
|||
implementation 'x:jmxri:1.2.1'
|
||||
}
|
||||
```
|
||||
4. Run the gradle build as needed with `--write-verification-metadata` to ensure the gradle dependency verification does not fail on your custom dependency.
|
||||
4. Run the Gradle build as needed with `--write-verification-metadata` to ensure the Gradle dependency verification does not fail on your custom dependency.
|
||||
|
||||
---
|
||||
**NOTE**
|
||||
|
|
@ -273,5 +272,5 @@ As Gradle prefers to use modules whose descriptor has been created from real met
|
|||
flat directory repositories cannot be used to override artifacts with real meta-data from other repositories declared in the build.
|
||||
For example, if Gradle finds only `jmxri-1.2.1.jar` in a flat directory repository, but `jmxri-1.2.1.pom` in another repository
|
||||
that supports meta-data, it will use the second repository to provide the module.
|
||||
Therefore, it is recommended to declare a version that is not resolvable from public repositories we use (e.g. maven central)
|
||||
Therefore, it is recommended to declare a version that is not resolvable from public repositories we use (e.g. Maven Central)
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
Contributing to elasticsearch
|
||||
Contributing to Elasticsearch
|
||||
=============================
|
||||
|
||||
Elasticsearch is a free and open project and we love to receive contributions from our community — you! There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into Elasticsearch itself.
|
||||
|
|
@ -54,7 +54,7 @@ The process for contributing to any of the [Elastic repositories](https://github
|
|||
### Fork and clone the repository
|
||||
|
||||
You will need to fork the main Elasticsearch code or documentation repository and clone it to your local machine. See
|
||||
[github help page](https://help.github.com/articles/fork-a-repo) for help.
|
||||
[GitHub help page](https://help.github.com/articles/fork-a-repo) for help.
|
||||
|
||||
Further instructions for specific projects are given below.
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ cycle.
|
|||
* Lines that are not part of your change should not be edited (e.g. don't format
|
||||
unchanged lines, don't reorder existing imports)
|
||||
* Add the appropriate [license headers](#license-headers) to any new files
|
||||
* For contributions involving the elasticsearch build you can find details about the build setup in the
|
||||
* For contributions involving the Elasticsearch build you can find details about the build setup in the
|
||||
[BUILDING](BUILDING.md) file
|
||||
|
||||
### Submitting your changes
|
||||
|
|
@ -89,7 +89,6 @@ Once your changes and tests are ready to submit for review:
|
|||
|
||||
Update your local repository with the most recent code from the main Elasticsearch repository, and rebase your branch on top of the latest main branch. We prefer your initial changes to be squashed into a single commit. Later, if we ask you to make changes, add them as separate commits. This makes them easier to review. As a final step before merging we will either ask you to squash all commits yourself or we'll do it for you.
|
||||
|
||||
|
||||
4. Submit a pull request
|
||||
|
||||
Push your local changes to your forked copy of the repository and [submit a pull request](https://help.github.com/articles/using-pull-requests). In the pull request, choose a title which sums up the changes that you have made, and in the body provide more details about what your changes do. Also mention the number of the issue where discussion has taken place, eg "Closes #123".
|
||||
|
|
@ -121,8 +120,7 @@ using the wrapper via the `gradlew` script on Unix systems or `gradlew.bat`
|
|||
script on Windows in the root of the repository. The examples below show the
|
||||
usage on Unix.
|
||||
|
||||
We support development in IntelliJ versions IntelliJ 2020.1 and
|
||||
onwards.
|
||||
We support development in [IntelliJ IDEA] versions 2020.1 and onwards.
|
||||
|
||||
[Docker](https://docs.docker.com/install/) is required for building some Elasticsearch artifacts and executing certain test suites. You can run Elasticsearch without building all the artifacts with:
|
||||
|
||||
|
|
@ -135,7 +133,7 @@ specifically these lines tell you that Elasticsearch is ready:
|
|||
[2020-05-29T14:50:35,167][INFO ][o.e.h.AbstractHttpServerTransport] [runTask-0] publish_address {127.0.0.1:9200}, bound_addresses {[::1]:9200}, {127.0.0.1:9200}
|
||||
[2020-05-29T14:50:35,169][INFO ][o.e.n.Node ] [runTask-0] started
|
||||
|
||||
But to be honest its typically easier to wait until the console stops scrolling
|
||||
But to be honest it's typically easier to wait until the console stops scrolling
|
||||
and then run `curl` in another window like this:
|
||||
|
||||
curl -u elastic:password localhost:9200
|
||||
|
|
@ -143,7 +141,7 @@ and then run `curl` in another window like this:
|
|||
|
||||
### Importing the project into IntelliJ IDEA
|
||||
|
||||
The minimum IntelliJ IDEA version required to import the Elasticsearch project is 2020.1
|
||||
The minimum IntelliJ IDEA version required to import the Elasticsearch project is 2020.1.
|
||||
Elasticsearch builds using Java 17. When importing into IntelliJ you will need
|
||||
to define an appropriate SDK. The convention is that **this SDK should be named
|
||||
"17"** so that the project import will detect it automatically. For more details
|
||||
|
|
@ -173,7 +171,7 @@ action is required.
|
|||
|
||||
#### Formatting
|
||||
|
||||
Elasticsearch code is automatically formatted with [spotless], backed by the
|
||||
Elasticsearch code is automatically formatted with [Spotless], backed by the
|
||||
Eclipse formatter. You can do the same in IntelliJ with the
|
||||
[Eclipse Code Formatter] so that you can apply the correct formatting directly in
|
||||
your IDE. The configuration for the plugin is held in
|
||||
|
|
@ -198,7 +196,7 @@ Alternative manual steps for IntelliJ.
|
|||
3. Navigate to the file `build-conventions/formatterConfig.xml`
|
||||
4. Click "OK"
|
||||
|
||||
### REST Endpoint Conventions
|
||||
### REST endpoint conventions
|
||||
|
||||
Elasticsearch typically uses singular nouns rather than plurals in URLs.
|
||||
For example:
|
||||
|
|
@ -214,7 +212,7 @@ but not:
|
|||
You may find counterexamples, but new endpoints should use the singular
|
||||
form.
|
||||
|
||||
### Java Language Formatting Guidelines
|
||||
### Java language formatting guidelines
|
||||
|
||||
Java files in the Elasticsearch codebase are automatically formatted using
|
||||
the [Spotless Gradle] plugin. All new projects are automatically formatted,
|
||||
|
|
@ -249,13 +247,13 @@ Please follow these formatting guidelines:
|
|||
only do this where the benefit clearly outweighs the decrease in formatting
|
||||
consistency.
|
||||
* Note that Javadoc and block comments i.e. `/* ... */` are not formatted,
|
||||
but line comments i.e `// ...` are.
|
||||
but line comments i.e. `// ...` are.
|
||||
* Negative boolean expressions must use the form `foo == false` instead of
|
||||
`!foo` for better readability of the code. This is enforced via
|
||||
Checkstyle. Conversely, you should not write e.g. `if (foo == true)`, but
|
||||
just `if (foo)`.
|
||||
|
||||
#### Editor / IDE Support
|
||||
#### Editor / IDE support
|
||||
|
||||
IntelliJ IDEs can
|
||||
[import](https://blog.jetbrains.com/idea/2014/01/intellij-idea-13-importing-code-formatter-settings-from-eclipse/)
|
||||
|
|
@ -316,7 +314,7 @@ is to be helpful, not to turn writing code into a chore.
|
|||
this is critical to understanding the code e.g. documenting the
|
||||
subtleties of the implementation of a private method. The point here
|
||||
is that implementations will change over time, and the Javadoc is
|
||||
less likely to become out-of-date if it only talks about the what is
|
||||
less likely to become out-of-date if it only talks about
|
||||
the purpose of the code, not what it does.
|
||||
8. Examples in Javadoc can be very useful, so feel free to add some if
|
||||
you can reasonably do so i.e. if it takes a whole page of code to set
|
||||
|
|
@ -362,7 +360,7 @@ Finally, use your judgement! Base your decisions on what will help other
|
|||
developers - including yourself, when you come back to some code
|
||||
3 months in the future, having forgotten how it works.
|
||||
|
||||
### License Headers
|
||||
### License headers
|
||||
|
||||
We require license headers on all Java files. With the exception of the
|
||||
top-level `x-pack` directory, all contributed code should have the following
|
||||
|
|
@ -433,7 +431,7 @@ In rare situations you may want to configure your `Logger` slightly
|
|||
differently, perhaps specifying a different class or maybe using one of the
|
||||
methods on `org.elasticsearch.common.logging.Loggers` instead.
|
||||
|
||||
If the log message includes values from your code then you must use use
|
||||
If the log message includes values from your code then you must use
|
||||
placeholders rather than constructing the string yourself using simple
|
||||
concatenation. Consider wrapping the values in `[...]` to help distinguish them
|
||||
from the static part of the message:
|
||||
|
|
@ -461,18 +459,18 @@ unit tests, especially if there is complex logic for computing what is logged
|
|||
and when to log it. You can use a `org.elasticsearch.test.MockLogAppender` to
|
||||
make assertions about the logs that are being emitted.
|
||||
|
||||
Logging is a powerful diagnostic technique but it is not the only possibility.
|
||||
Logging is a powerful diagnostic technique, but it is not the only possibility.
|
||||
You should also consider exposing some information about your component via an
|
||||
API instead of in logs. For instance you can implement APIs to report its
|
||||
API instead of in logs. For instance, you can implement APIs to report its
|
||||
current status, various statistics, and maybe even details of recent failures.
|
||||
|
||||
#### Log levels
|
||||
|
||||
Each log message is written at a particular _level_. By default Elasticsearch
|
||||
Each log message is written at a particular _level_. By default, Elasticsearch
|
||||
will suppress messages at the two most verbose levels, `TRACE` and `DEBUG`, and
|
||||
will output messages at all other levels. Users can configure which levels of
|
||||
message are written by each logger at runtime, but you should expect everyone
|
||||
to run with the default configuration almost all of the time and choose your
|
||||
to run with the default configuration almost all the time and choose your
|
||||
levels accordingly.
|
||||
|
||||
The guidance in this section is subjective in some areas. When in doubt,
|
||||
|
|
@ -570,7 +568,7 @@ an index template is created or updated:
|
|||
`INFO`-level logging is enabled by default so its target audience is the
|
||||
general population of users and administrators. You should use user-facing
|
||||
terminology and ensure that messages at this level are self-contained. In
|
||||
general you shouldn't log unusual events, particularly exceptions with stack
|
||||
general, you shouldn't log unusual events, particularly exceptions with stack
|
||||
traces, at `INFO` level. If the event is relatively benign then use `DEBUG`,
|
||||
whereas if the user should be notified then use `WARN`.
|
||||
|
||||
|
|
@ -629,7 +627,7 @@ the logs.
|
|||
|
||||
##### `ERROR`
|
||||
|
||||
This is the next least verbose level after `WARN`. In theory it is possible for
|
||||
This is the next least verbose level after `WARN`. In theory, it is possible for
|
||||
users to suppress messages at `WARN` and below, believing this to help them
|
||||
focus on the most important `ERROR` messages, but in practice in Elasticsearch
|
||||
this will hide so much useful information that the resulting logs will be
|
||||
|
|
@ -660,7 +658,7 @@ numbering scheme separate to release version. The main ones are
|
|||
inter-node binary protocol and index data + metadata respectively.
|
||||
|
||||
Separated version numbers are comprised of an integer number. The semantic
|
||||
meaing of a version number are defined within each `*Version` class. There
|
||||
meaning of a version number are defined within each `*Version` class. There
|
||||
is no direct mapping between separated version numbers and the release version.
|
||||
The versions used by any particular instance of Elasticsearch can be obtained
|
||||
by querying `/_nodes/info` on the node.
|
||||
|
|
@ -692,12 +690,12 @@ feature in a cluster:
|
|||
in a class related to the change you're doing.
|
||||
2. Return that constant from an instance of `FeatureSpecification.getFeatures`,
|
||||
either an existing implementation or a new implementation. Make sure
|
||||
the implementation is added as a SPI implementation in `module-info.java`
|
||||
the implementation is added as an SPI implementation in `module-info.java`
|
||||
and `META-INF/services`.
|
||||
3. To check if all nodes in the cluster support the new feature, call
|
||||
`FeatureService.clusterHasFeature(ClusterState, NodeFeature)`
|
||||
|
||||
### Creating A Distribution
|
||||
### Creating a distribution
|
||||
|
||||
Run all build commands from within the root directory:
|
||||
|
||||
|
|
@ -727,7 +725,7 @@ The archive distributions (tar and zip) can be found under:
|
|||
|
||||
./distribution/archives/(darwin-tar|linux-tar|windows-zip|oss-darwin-tar|oss-linux-tar|oss-windows-zip)/build/distributions/
|
||||
|
||||
### Running The Full Test Suite
|
||||
### Running the full test suite
|
||||
|
||||
Before submitting your changes, run the test suite to make sure that nothing is broken, with:
|
||||
|
||||
|
|
@ -752,14 +750,14 @@ a test that passes locally, may actually fail later due to random settings
|
|||
or data input. To make tests repeatable, a `REPRODUCE` line in CI will also include
|
||||
the `-Dtests.seed` parameter.
|
||||
|
||||
When running locally, gradle does its best to take advantage of cached results.
|
||||
When running locally, Gradle does its best to take advantage of cached results.
|
||||
So, if the code is unchanged, running the same test with the same `-Dtests.seed`
|
||||
repeatedly may not actually run the test if it has passed with that seed
|
||||
in the previous execution. A way around this is to pass a separate parameter
|
||||
to adjust the command options seen by gradle.
|
||||
to adjust the command options seen by Gradle.
|
||||
A simple option may be to add the parameter `-Dtests.timestamp=$(date +%s)`
|
||||
which will give the current time stamp as a parameter, thus making the parameters
|
||||
sent to gradle unique and bypassing the cache.
|
||||
sent to Gradle unique and bypassing the cache.
|
||||
|
||||
### Project layout
|
||||
|
||||
|
|
@ -776,9 +774,9 @@ Builds our tar and zip archives and our rpm and deb packages.
|
|||
Libraries used to build other parts of the project. These are meant to be
|
||||
internal rather than general purpose. We have no plans to
|
||||
[semver](https://semver.org/) their APIs or accept feature requests for them.
|
||||
We publish them to maven central because they are dependencies of our plugin
|
||||
test framework, high level rest client, and jdbc driver but they really aren't
|
||||
general purpose enough to *belong* in maven central. We're still working out
|
||||
We publish them to Maven Central because they are dependencies of our plugin
|
||||
test framework, high level rest client, and jdbc driver, but they really aren't
|
||||
general purpose enough to *belong* in Maven Central. We're still working out
|
||||
what to do here.
|
||||
|
||||
#### `modules`
|
||||
|
|
@ -789,7 +787,7 @@ they depend on libraries that we don't believe *all* of Elasticsearch should
|
|||
depend on.
|
||||
|
||||
For example, reindex requires the `connect` permission so it can perform
|
||||
reindex-from-remote but we don't believe that the *all* of Elasticsearch should
|
||||
reindex-from-remote, but we don't believe that the *all* of Elasticsearch should
|
||||
have the "connect". For another example, Painless is implemented using antlr4
|
||||
and asm and we don't believe that *all* of Elasticsearch should have access to
|
||||
them.
|
||||
|
|
@ -828,7 +826,7 @@ qa project, open a PR and be ready to discuss options.
|
|||
|
||||
#### `server`
|
||||
The server component of Elasticsearch that contains all of the modules and
|
||||
plugins. Right now things like the high level rest client depend on the server
|
||||
plugins. Right now things like the high level rest client depend on the server,
|
||||
but we'd like to fix that in the future.
|
||||
|
||||
#### `test`
|
||||
|
|
@ -848,7 +846,7 @@ the `qa` subdirectory functions just like the top level `qa` subdirectory. The
|
|||
`plugin` subdirectory contains the x-pack module which runs inside the
|
||||
Elasticsearch process.
|
||||
|
||||
### Gradle Build
|
||||
### Gradle build
|
||||
|
||||
We use Gradle to build Elasticsearch because it is flexible enough to not only
|
||||
build and package Elasticsearch, but also orchestrate all of the ways that we
|
||||
|
|
@ -865,16 +863,20 @@ common configurations in our build and how we use them:
|
|||
at compile and runtime but are not exposed as a compile dependency to other dependent projects.
|
||||
Dependencies added to the `implementation` configuration are considered an implementation detail
|
||||
that can be changed at a later date without affecting any dependent projects.</dd>
|
||||
|
||||
<dt>`api`</dt><dd>Dependencies that are used as compile and runtime dependencies of a project
|
||||
and are considered part of the external api of the project.
|
||||
and are considered part of the external api of the project.</dd>
|
||||
|
||||
<dt>`runtimeOnly`</dt><dd>Dependencies that not on the classpath at compile time but
|
||||
are on the classpath at runtime. We mostly use this configuration to make sure that
|
||||
we do not accidentally compile against dependencies of our dependencies also
|
||||
known as "transitive" dependencies".</dd>
|
||||
|
||||
<dt>`compileOnly`</dt><dd>Code that is on the classpath at compile time but that
|
||||
should not be shipped with the project because it is "provided" by the runtime
|
||||
somehow. Elasticsearch plugins use this configuration to include dependencies
|
||||
that are bundled with Elasticsearch's server.</dd>
|
||||
|
||||
<dt>`testImplementation`</dt><dd>Code that is on the classpath for compiling tests
|
||||
that are part of this project but not production code. The canonical example
|
||||
of this is `junit`.</dd>
|
||||
|
|
@ -897,7 +899,7 @@ time is very limited. In some cases the time we would need to spend on reviews
|
|||
would outweigh the benefits of a change by preventing us from working on other
|
||||
more beneficial changes instead.
|
||||
|
||||
Please discuss your change in a Github issue before spending much time on its
|
||||
Please discuss your change in a GitHub issue before spending much time on its
|
||||
implementation. We sometimes have to reject contributions that duplicate other
|
||||
efforts, take the wrong approach to solving a problem, or solve a problem which
|
||||
does not need solving. An up-front discussion often saves a good deal of wasted
|
||||
|
|
@ -980,8 +982,8 @@ Finally, we require that you run `./gradlew check` before submitting a
|
|||
non-documentation contribution. This is mentioned above, but it is worth
|
||||
repeating in this section because it has come up in this context.
|
||||
|
||||
[intellij]: https://blog.jetbrains.com/idea/2017/07/intellij-idea-2017-2-is-here-smart-sleek-and-snappy/
|
||||
[IntelliJ IDEA]: https://www.jetbrains.com/idea/
|
||||
[Checkstyle]: https://plugins.jetbrains.com/plugin/1065-checkstyle-idea
|
||||
[spotless]: https://github.com/diffplug/spotless
|
||||
[Spotless]: https://github.com/diffplug/spotless
|
||||
[Eclipse Code Formatter]: https://plugins.jetbrains.com/plugin/6546-eclipse-code-formatter
|
||||
[Spotless Gradle]: https://github.com/diffplug/spotless/tree/main/plugin-gradle
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue