OpenSearch Open-Source Contributor Curriculum
Welcome to the OpenSearch Open-Source Contributor Curriculum — a complete, implementation-heavy roadmap for engineers who want to become serious OpenSearch contributors and eventually operate at the level of a core contributor, maintainer, or TSC-aware engineer.
What This Curriculum Is
This is not a tutorial. It is a structured engineering apprenticeship built around how OpenSearch is actually developed, tested, reviewed, and maintained by its maintainers and the Technical Steering Committee.
Every level is tied to real OpenSearch source code, real GitHub issue patterns, real test infrastructure, and real contribution workflows. The labs mirror the work an OpenSearch maintainer actually does — reading the coordination layer, tracing a search request from REST handler to Lucene, debugging shard allocation, reproducing reported issues, and preparing pull requests for community review.
The curriculum will not hold your hand. It will point you at the right parts of the codebase, give you the right questions to ask, and push you to develop the muscle memory of someone who works at this level habitually.
Who This Is For
This curriculum is designed for strong backend and distributed systems engineers who:
- Have 3+ years of Java development experience (Gradle-based projects are a plus)
- Are comfortable with HTTP/REST APIs and JSON
- Understand distributed systems fundamentals: replication, consensus, sharding, failure detection
- Want to contribute to open source at a serious level — not just fix typos
You should be comfortable with:
- Reading large, unfamiliar Java codebases without a guide
gitworkflows, reading diffs, working with GitHub pull requests- The search/storage domain at a high level: inverted indexes, documents, queries, aggregations
- Distributed execution concepts: leader election, quorums, primary/replica data flow
You do not need prior Apache Lucene experience. You will build it here.
What You Will Be Able to Do
After completing this curriculum, you will be able to:
| Capability | Description |
|---|---|
| Build and test | Build OpenSearch from source with Gradle, run unit/integration tests, launch a local cluster |
| Navigate the codebase | Find any class, understand its role, trace execution across module boundaries |
| Understand the request path | Follow a request from REST handler through transport actions to shards and Lucene |
| Reason about coordination | Explain cluster-manager election, cluster state publishing, and the applier/listener model |
| Debug failures | Diagnose unassigned shards, failing recoveries, search errors, and circuit-breaker trips |
| Master the engine | Trace indexing through IndexShard/InternalEngine/Translog and search through query/fetch phases |
| Contribute pull requests | Reproduce issues, fix bugs, write tests, prepare high-quality PRs with CHANGELOG + DCO |
| Engage the community | Interact productively on GitHub, the forum, and in community meetings |
| Extend the engine | Build a plugin, add a REST action, custom analyzer, or aggregation |
| Think like a maintainer | Reason about wire/index backward compatibility, test stability, performance, and release impact |
How to Use This Curriculum
Work through the 9 levels sequentially. Do not skip levels. Each level builds directly on the previous one, and the labs depend on the conceptual foundations laid earlier.
| Level | Title | Core Focus |
|---|---|---|
| 1 | Lucene and OpenSearch Foundation | Build, test, first cluster, where OpenSearch fits |
| 2 | OpenSearch Contributor Onboarding | GitHub workflow, PRs, DCO, CHANGELOG, first fix |
| 3 | OpenSearch Architecture | Nodes, shards, REST → Transport → Action, threadpools |
| 4 | Cluster Coordination and State | Cluster-manager election, cluster state, allocation |
| 5 | Testing and Debugging | Test framework, InternalTestCluster, flaky tests |
| 6 | Indexing Path and Storage Engine | IndexShard, InternalEngine, translog, mappings |
| 7 | Search Path and Aggregations | Query/fetch phases, aggregations, the coordinating reduce |
| 8 | Real Issue Contribution | GitHub reproduction, root cause analysis, real PRs |
| 9 | Advanced Maintainer / TSC | Backward compatibility, performance, release practices |
Beyond the 9 levels, the curriculum includes five additional sections:
| Section | Purpose |
|---|---|
| Contributor Mindset | How to think, behave, and grow as an OpenSearch contributor |
| Issue Roadmap | Staged progression from beginner-friendly to release-blocking issues |
| Internals Deep Dives | 24 focused deep dives, each with a mini-lab |
| Plugins, Extensions & Cross-Repo Labs | Cross-project debugging, Dashboards-to-core tracing, plugin internals |
| Release, Review & Governance Practices | Foundation governance, release trains, licensing, the TSC |
The curriculum closes with a Capstone Project — a full contribution cycle from issue reproduction to merged pull request and engineering write-up.
Required Tools
Before starting Level 1, ensure you have the following installed and working:
JDK 21 (the OpenSearch 3.x baseline; the repo also bundles its own JDK for the build)
Git 2.x
IntelliJ IDEA (strongly recommended) or Eclipse
Docker (optional — useful for multi-node and packaging experiments)
A modern shell with curl (for hitting the local cluster's REST API on :9200)
Note on the build: OpenSearch builds with Gradle via the
./gradlewwrapper — you do not install Gradle yourself, and the wrapper provisions a matching JDK for the build. You only need a system JDK to run tools and your IDE. Always checkgradle/andbuild.gradleon the branch you are working on for the exact baseline.
You will also need:
- A clone of the OpenSearch repository (the core engine — where you will spend ~90% of your time)
- Optionally, a clone of OpenSearch Dashboards (the UI — needed only for the cross-repo labs)
- A free GitHub account with your local
gitconfigured for DCO sign-off (git config commit.gpgsignoptional;git commit -srequired) - An account on the OpenSearch community forum and the public Slack (optional but recommended)
Note on contribution mechanics: OpenSearch uses GitHub pull requests, not patches or a JIRA. Every PR requires a Developer Certificate of Origin sign-off (
Signed-off-by:line viagit commit -s) and a CHANGELOG.md entry. There is no CLA.
OpenSearch at a Glance
OpenSearch is a distributed search and analytics engine built on top of Apache Lucene. It powers full-text search, log analytics, observability, and security analytics workloads. It is the open-source (Apache 2.0) successor to the Elasticsearch 7.10.2 codebase, from which it was forked in 2021.
Why OpenSearch Exists
OpenSearch was created when Elasticsearch and Kibana were relicensed away from Apache 2.0 under the SSPL/Elastic License in early 2021. The community needed a permissively licensed, openly governed search engine. OpenSearch is that engine: Apache 2.0, governed by the OpenSearch Software Foundation under the Linux Foundation, with a Technical Steering Committee and per-repo maintainers.
What OpenSearch Does
- Stores JSON documents in indices, each split into shards (primary + replica)
- Each shard is an Apache Lucene index of immutable segments
- Distributes shards across nodes and keeps them allocated and balanced
- Elects a cluster manager (formerly "master") that owns the authoritative cluster state
- Serves a REST API on port 9200 and an internal transport protocol on 9300
- Executes queries and aggregations by fanning out to shards and reducing the results
Key Modules
You will spend the majority of your time in these areas:
| Area | Path | Description |
|---|---|---|
| Core engine | server/ | Cluster, nodes, shards, indexing, search, allocation — org.opensearch.* |
| Shared libs | libs/ | libs/core (serialization), libs/x-content (XContent), libs/common |
| Bundled modules | modules/ | transport-netty4, reindex, lang-painless, analysis-common |
| In-repo plugins | plugins/ | analysis-icu, repository-s3, discovery-ec2, and more |
| Test framework | test/framework/ | OpenSearchTestCase, OpenSearchIntegTestCase, InternalTestCluster |
| BWC / QA | qa/ | Backward-compatibility, rolling-upgrade, packaging tests |
| REST specs | rest-api-spec/ | REST API JSON specs and shared YAML tests |
Key Classes (High-Level Preview)
| Class | Area | Role |
|---|---|---|
Node | server | A running OpenSearch node; wires up all services |
ClusterService | server | Ties together cluster-manager service + applier service |
ClusterState | server | The immutable, versioned snapshot of cluster metadata |
Coordinator | server | The consensus/coordination layer (election, joins, publish) |
AllocationService | server | Decides where shards go, gated by AllocationDeciders |
RestController | server | Routes HTTP requests to RestHandlers |
TransportAction | server | Server-side action invoked by the NodeClient |
IndicesService / IndexShard | server | Manages indices and per-shard lifecycle |
InternalEngine | server | Wraps Lucene IndexWriter + translog; the write path |
SearchService | server | Executes query and fetch phases on a shard |
Plugin | server | Base class for all extensions |
If half of these are unfamiliar, that is expected. By Level 4 you will read them without a guide.
The OpenSearch Community
OpenSearch is a large, active, openly governed project. The codebase reflects both its Elasticsearch heritage and years of independent evolution (segment replication, the cluster-manager rename, the Extensions SDK, remote-backed storage). Many design decisions live in GitHub issues, RFCs, and recorded community meetings rather than in code comments.
What the community values:
- Pull requests that include tests and a CHANGELOG entry
- Issues that include a clear, minimal reproduction
- Comments that demonstrate you have read the existing code
- Contributors who engage respectfully and patiently across GitHub, the forum, and Slack
- Sustained contribution over time, not one-off patches
The path from contributor to maintainer is measured in months to years, not weeks. That is intentional. Maintainership is earned through sustained, high-quality contribution and demonstrated judgment — not volume of PRs.
This curriculum will help you build the habits and depth of understanding that make that path realistic.
Begin with Level 1: Lucene and OpenSearch Foundation.