How to contribute

This section walks through the day-to-day mechanics of working in the Elasticsearch repository. The authoritative documents are CONTRIBUTING.md, BUILDING.md, TESTING.asciidoc, and AGENTS.md in the repo root; the pages here summarize them.

Picking up work

• All work starts from a GitHub issue. Triage labels include >bug, >enhancement, >feature, plus area labels like :Search, :Distributed/Coordination, :Analytics/ESQL. Look for good first issue and help wanted.
• Sign the Contributor License Agreement once.
• Discuss the design on the issue before writing the patch — the project's review cycle is long and the maintainers prefer to align on approach early.

Writing the change

• Keep diffs small and tightly scoped. Don't reformat unrelated lines.
• Match existing patterns. The codebase has strong conventions for action wiring, transport messages, REST handlers, listeners, and threading; see Patterns and conventions.
• Add Javadoc to new public/abstract methods explaining the why, not the what.
• If you change a Writeable (the binary wire format), add a transport version constant — see Patterns and conventions.
• Insert the correct license header (the IDE template covers both the default and the x-pack-only variants).

PR mechanics

1. Fork and branch off main.
2. Push and open the PR with a meaningful title (used as the squash commit message — keep it ≤50 chars where possible, max 72).
3. CI runs Buildkite pipelines: unit tests, REST tests, integration tests, BWC tests, smoke tests, and Spotless.
4. Address review comments by adding commits (no force-push to a public branch).
5. Maintainers merge with squash; backport bots open backports to active branches.

Definition of done

A PR is mergeable when:

• All CI is green (or the only failures are tracked muted tests not introduced by the PR).
• Spotless and precommit pass.
• New code paths are covered by unit tests, with an integration test if behavior is observable from the REST layer.
• Changelog entries are auto-generated; you don't need to hand-edit them as an external contributor.
• Two maintainers approve and the area owner LGTMs.

See:

• Development workflow — the loop of edit / build / test / commit.
• Testing — frameworks, harnesses, and how to reproduce CI failures.
• Debugging — logs, slow logs, and attaching a debugger.
• Patterns and conventions — the shape new code should take.
• Tooling — Gradle plugins, code generators, CI infrastructure, and developer scripts.