Level 8: Real Issue Contribution

Every level before this one was curated. You built from source against a known-good baseline, you traced code paths someone chose for you, and you implemented labs with a known answer. Level 8 is different. Here you contribute to OpenSearch the way maintainers actually work: you find a real, open GitHub issue, reproduce it deterministically, root-cause it, fix it with a minimal diff, write the test that fails-then-passes, and open a Pull Request that meets merge quality.

There is no answer key. The issue may be mis-triaged. The "obvious" fix may be wrong. The repro may be flaky. That is the job. This level teaches you the loop that the rest of your contributor life runs on, and it deliberately hands you less scaffolding than any prior level.

Learning Objectives

By the end of Level 8 you must be able to:

  1. Find a tractable real issue in opensearch-project/OpenSearch and judge whether it is in scope for you.
  2. Build a deterministic reproducer (a failing JUnit test, or a curl/REST-YAML sequence on ./gradlew run) that fails on main and will pass after the fix.
  3. Separate the symptom (what the reporter saw) from the trigger conditions (what is actually required to provoke it).
  4. Implement a minimal-diff fix with the SPDX header, spotlessApply, and a CHANGELOG.md entry.
  5. Open a merge-quality Pull Request: DCO sign-off (git commit -s), a filled-in PR template, green CI, and a description a reviewer can act on.
  6. Improve error messages and diagnostics as a focused, high-value contribution type.

The End-to-End Contribution Cycle (preview)

Everything in this level — and the Capstone — is one loop:

flowchart LR
    F[Find issue<br/>good first issue / bug] --> R[Reproduce<br/>deterministic, fails on main]
    R --> C[Root cause<br/>grep + read + debug]
    C --> X[Fix<br/>minimal diff]
    X --> T[Test<br/>fails-then-passes]
    T --> P[PR<br/>DCO + CHANGELOG + template]
    P --> CI[CI + review]
    CI -->|changes requested| X
    CI -->|approved| M[Merge + backport label]

The non-obvious truth: the reproducer, not the fix, is the center of gravity. A bug you can reproduce on demand is a bug you can fix with confidence; one you cannot is a guess. Maintainers look for the reproducer first. Lab 8.1 is entirely about building one.

How This Level Differs From Levels 1–7

Earlier levelsLevel 8
Curated labs with a known answerReal open issues, possibly mis-triaged
Code path chosen for youYou locate the code from a symptom
Repro providedYou build the repro from a bug report
"Make it compile / pass""Make a reviewer say yes"
No external stakesA real PR, real CI, real maintainers

You bring the skills from prior levels: reading the codebase (Level 1), the request/transport path (Levels 2–3), cluster state and allocation (Levels 4–5), the engine (Level 6), and search/aggs (Level 7). Level 8 is where they combine on a target you did not choose.

Finding a Tractable Issue

Browse github.com/opensearch-project/OpenSearch/issues and filter with these labels:

LabelWhat it signalsGood for you now?
good first issueMaintainers vetted it as small and self-containedYes — start here
help wantedMaintainers want a contributor; may be largerSometimes
bugA defect with (ideally) a repro in the issueYes, if scoped
flaky-testA test that fails intermittentlyYes — see Level 9 / stage-9
enhancementNew behavior; needs design buy-inNot yet (needs an RFC discussion)
untriagedNot yet reviewed by a maintainerRisky — may be invalid

GitHub search you can paste into the issues search box:

is:open is:issue label:"good first issue" repo:opensearch-project/OpenSearch

is:open is:issue label:bug label:"help wanted" sort:updated-desc

Triage checklist before you claim an issue:

  • Read the entire thread. Is someone already assigned or has an open PR?
  • Is the symptom described concretely enough to reproduce?
  • Is it in a subsystem you can actually read (server core, not a separate plugin repo)?
  • Is it small? A first contribution should touch a handful of files, not the coordination layer.
  • Comment that you are investigating before you sink a day into it — avoid duplicate work.

Warning: Do not open a PR against an issue someone else is actively working. Check for linked PRs and recent comments. The community norm is: announce intent, then work.

The Deliverables of a Real PR

A merge-quality OpenSearch PR contains, at minimum:

ArtifactWhereWhy
Minimal code diffserver/ (or the relevant module)The fix, with SPDX headers intact
A test that fails-then-passes*Tests.java / *IT.java / *.ymlProves the bug and guards regression
CHANGELOG.md entryone line under ## [Unreleased ...]Required by precommit
DCO sign-offevery commit (git commit -s)OpenSearch requires DCO, not a CLA
Filled PR template.github/pull_request_template.mdDescription, related issue, checklist
Green CIGitHub Actions on the PRprecommit, tests, gradle check

The labs in this level produce exactly these artifacts.

Key Practices

PracticeWhat it meansTooling
Repro firstFail on main before you touch the fixJUnit / curl / REST-YAML
Minimal diffChange only what the bug requiresgit diff, no drive-by reformat
Fails-then-passes testRevert the fix → test red; apply → green./gradlew :server:test --tests ...
Run the gate locallyDon't burn CI to find a checkstyle nit./gradlew spotlessApply precommit
DCO sign-offSigned-off-by: on every commitgit commit -s
One logical changeOne issue, one PRrebase, not bundle
CHANGELOG hygieneAdd/Changed/Fixed/Deprecated/Removededit CHANGELOG.md

Labs

LabTitleOutput
8.1Reproduce an Existing GitHub IssueA deterministic reproducer that fails on main
8.2Implement the Fix, Write the Test, Open the PRA merge-quality PR with a fails-then-passes test
8.3Improve Error Messages and DiagnosticsA diagnostics PR with a message-asserting unit test

Deliverables

You must demonstrate all of the following before advancing to Level 9:

  • A chosen real (or real-feeling) issue with a written triage note (scope, assignee check, plan).
  • A deterministic reproducer that fails on main (Lab 8.1).
  • A minimal-diff fix and a fails-then-passes test (Lab 8.2).
  • A CHANGELOG.md entry and DCO-signed commits.
  • A PR (or a complete PR-ready branch + filled template, if not submitting upstream).
  • One diagnostics improvement with a unit test asserting the new message (Lab 8.3).

Common Mistakes

MistakeConsequenceFix
Fixing before reproducingYou "fix" the wrong thing; can't prove itBuild the repro first; it must fail on main
Test that passes before the fixProves nothing; reviewer rejectsRevert the fix and confirm the test goes red
Drive-by reformatting in the diffReviewer can't see the real changeKeep the diff minimal; reformat in a separate PR
Forgetting the CHANGELOG entryprecommit fails CIAdd the one-liner under [Unreleased]
Forgetting git commit -sDCO check blocks the PRSign off every commit (-s)
Bundling two fixes in one PRHard to review; stallsOne issue per PR
Picking an enhancement as a first PRNeeds design buy-in; spins foreverStart with good first issue / bug

Where This Level Points Next