Community Interaction: GitHub, Forum, and Slack

You can write a perfect patch and still get nowhere if you talk to the OpenSearch community the wrong way. Maintainers are volunteers and paid engineers with finite attention; the way you ask, claim, report, and escalate either earns that attention or spends it. This chapter is the operational etiquette of OpenSearch's communication channels — which one to use, how to use it well, and how to escalate a stalled effort without burning the bridge you will need next month.

The Channels and What Each Is For

OpenSearch has several channels, and using the wrong one is itself a mild faux pas (asking a deep design question in Slack, or a "how do I configure X" support question on a code PR).

The single most important rule: the durable record is GitHub. A decision made in Slack or a meeting is not real until it is written into an issue or PR. When something is decided in an ephemeral channel, the contributor's job is to capture it in the relevant issue. Maintainers notice who does this; it is low-effort, high-trust behavior.

Note: There is no JIRA and no dev@ mailing list as the working channel. If you are used to Apache, mentally remap: "open a JIRA" → "open a GitHub issue"; "post to dev@" → "comment on the issue / forum thread"; "attach a patch" → "open a PR."

When To Use Which — A Decision Guide

flowchart TD
    A[I have a thing to say] --> B{Is it a concrete defect<br/>or a specific feature ask?}
    B -- Yes --> C[Open a GitHub issue<br/>with repro + version]
    B -- No --> D{Is it about a specific<br/>change in flight?}
    D -- Yes --> E[Comment on that PR]
    D -- No --> F{Is it open-ended design<br/>or user-impact discussion?}
    F -- Yes --> G[Start a forum thread<br/>or RFC issue]
    F -- No --> H{Is it a quick,<br/>throwaway question?}
    H -- Yes --> I[Ask in Slack]
    H -- No --> G

If you find yourself about to ask the same question in two channels, stop — pick the durable one (issue or forum) and link to it from the ephemeral one.

How To File a Good Issue

A maintainer should be able to act on your issue with zero follow-up questions. The repo ships issue templates (bug report, feature request) — fill them out fully. The non-negotiable elements of a bug report:

1. Version: exact OpenSearch version and line (3.0.0, 2.x, built from main at SHA).
2. Environment: JVM, OS, single vs multi-node, relevant plugins, opensearch.yml deltas.
3. A minimal reproduction: the smallest sequence of curl/REST calls that triggers it.
4. Expected vs actual: what you expected, what happened, and the exact error/stack trace.
5. Logs: the relevant log lines (not a 50 MB dump) — and the full stack trace if there is one.

A reproduction maintainers love is copy-pasteable and self-contained:

# Repro for: aggregation returns wrong doc_count after delete-by-query (OpenSearch 3.0.0)
curl -s -XPUT 'localhost:9200/demo' -H 'content-type: application/json' -d '{
  "mappings": { "properties": { "status": { "type": "keyword" } } }
}'
curl -s -XPOST 'localhost:9200/demo/_doc?refresh=true' -H 'content-type: application/json' -d '{"status":"open"}'
curl -s -XPOST 'localhost:9200/demo/_delete_by_query?refresh=true' -H 'content-type: application/json' -d '{"query":{"term":{"status":"open"}}}'
# Expected: terms agg returns doc_count 0 for "open"
# Actual:   returns doc_count 1
curl -s 'localhost:9200/demo/_search?size=0' -H 'content-type: application/json' -d '{
  "aggs": { "by_status": { "terms": { "field": "status" } } }
}'

What kills an issue's chances: no version, "it doesn't work," a screenshot of a stack trace (post text), a giant unfocused log, or a reproduction that depends on your private cluster. Search first — is:issue <keywords> — and link any duplicate or related issue you find.

How To Claim an Issue You Want To Work On

OpenSearch does not formally "assign" most issues to non-maintainers up front. The convention is to comment your intent on the issue:

"I'd like to take this. My plan is to add a Version-gated field to XRequest and a round-trip serialization test. I'll open a draft PR this week — please let me know if someone is already on it or if the approach is wrong."

This does three things: signals you, states an approach a maintainer can correct before you write code, and sets a loose timeline. Then:

• Wait for a brief acknowledgement on good first issue / help wanted issues — they exist precisely to be claimed; a maintainer will usually thumbs-up or comment.
• Do not silently start large work on an untriaged issue or an open RFC — the design may not be settled, and you risk building the wrong thing. Ask first.
• If you go quiet for weeks after claiming, expect (and accept) someone else picking it up. A short "still working on this, blocked on X" comment keeps your claim alive.

Triage Labels You Must Recognize

Labels are the maintainers' workflow. Reading them tells you whether an issue is ready for you:

Warning: Do not start building on an untriaged or RFC-labeled issue as if the design were final. untriaged means no maintainer has agreed it should be done at all. The fastest way to waste a weekend is to implement an unendorsed proposal.

How To Escalate a Stalled PR — Politely

PRs go quiet. Maintainers are busy, reviewers get reassigned, CI breaks on main and masks your status. Escalation is legitimate; impatience is not. The cadence:

1. Wait a reasonable interval. A few business days of silence on an open PR is normal. Do not ping after 12 hours.
2. First nudge — on the PR, factual and specific:

   "Friendly ping — this has been green for a week and addresses #1234. Is there anything you'd like me to change, or is it waiting on a reviewer? Happy to rebase if main has moved."

3. Find the right reviewer. Check MAINTAINERS.md and the CODEOWNERS for the touched paths; @-mention a maintainer for that area (one, not all of them).
4. Use the forum or Slack as a pointer, not a venue. A short "could a maintainer take a look at #5678?" in the relevant Slack channel is fine; do not re-litigate the change there.
5. Raise it in a community meeting only if it is genuinely stuck and important — and add a one-line note to the PR afterward capturing whatever was said.

What never works: pinging daily, @-mentioning the entire maintainer list, editing the PR title to "PLEASE REVIEW", or arguing that your PR is more important than others in the queue.

Etiquette: Dos and Don'ts

Code of Conduct

OpenSearch publishes a CODE_OF_CONDUCT.md in the repo (it follows a Contributor-Covenant-style standard) and the OpenSearch Software Foundation has its own conduct expectations. Read it once:

find ~/os-src -maxdepth 1 -iname 'CODE_OF_CONDUCT.md'

The substance is unremarkable and binding: be respectful, assume good faith, no harassment, no personal attacks, keep technical disagreement technical. The practical version for a contributor: disagree with the idea, never the person; when a maintainer says no, ask "what would change your mind?" rather than escalating in tone; and if you see conduct issues, use the private reporting path in the document rather than a public flame. Trust in this project is slow to build and fast to lose — see the maintainership chapter — and conduct is the foundation of it.

Validation: Prove You Understand This

1. Given a defect you found, write the full GitHub issue body — version, environment, a copy-pasteable curl repro, expected vs actual, and the relevant log lines.
2. Draft the comment you would post to claim a good first issue, including your intended approach and a timeline.
3. For a hypothetical stalled, green PR, write the escalation cadence: when you nudge, who you @-mention (and how you found them via MAINTAINERS.md), and what you do not do.
4. State which channel you'd use for each of: a NullPointerException with a repro; "should the default for setting X change?"; "what time is the community meeting?"; a decision reached in Slack that needs to become real.
5. Explain why "the durable record is GitHub" changes how you capture a Slack decision.

When your issues need no follow-up and your nudges land without friction, you are ready to ship. The next chapter — PR Quality and Preparation — is what a maintainer expects to see when you do.