Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Finish contributing updates; thanks @acarbonetto #12981

Merged
merged 17 commits into from
Apr 5, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 26 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
- [Contributing to OpenSearch](#contributing-to-opensearch)
- [First Things First](#first-things-first)
- [Ways to Contribute](#ways-to-contribute)
- [First Things First](#first-things-first)
- [Ways to Contribute](#ways-to-contribute)
- [Bug Reports](#bug-reports)
- [Feature Requests](#feature-requests)
- [Documentation Changes](#documentation-changes)
- [Contributing Code](#contributing-code)
- [Developer Certificate of Origin](#developer-certificate-of-origin)
- [Changelog](#changelog)
- [Review Process](#review-process)
- [Troubleshooting Failing Builds](#troubleshooting-failing-builds)
- [Developer Certificate of Origin](#developer-certificate-of-origin)
- [Changelog](#changelog)
- [Review Process](#review-process)

# Contributing to OpenSearch

Expand Down Expand Up @@ -164,13 +163,28 @@ If we accept the PR, a [maintainer](MAINTAINERS.md) will merge your change and u

If we reject the PR, we will close the pull request with a comment explaining why. This decision isn't always final: if you feel we have misunderstood your intended change or otherwise think that we should reconsider then please continue the conversation with a comment on the PR and we'll do our best to address any further points you raise.

We have a lot of mechanisms to help expedite towards an accepted PR. Here are some tips for success:
1. *Minimize BWC guarantees*: First PR review heavily focuses on the public facing API. This is what we have to "guarantee" as non-breaking for [bwc across major versions](./DEVELOPER_GUIDE.md#backwards-compatibility).
2. *Do not copy non-compliant code*: Ensure that code is APLv2 compatible. This means that you have not copied any code from other sources unless that code is also APLv2 compatible.
3. *Use feature flags*: New features that are guarded behind a feature flag have a higher chance of being merged and backported since... they're guarded by feature flag ([Feature PR](https://github.com/opensearch-project/OpenSearch/pull/4959)).
4. *Use appropriate java tags*:
stephen-crawford marked this conversation as resolved.
Show resolved Hide resolved
- `@opensearch.internal`: Marks internal classes that may change rapidly.
stephen-crawford marked this conversation as resolved.
Show resolved Hide resolved
- `@opensearch.api`: Marks public facing API classes that provide bwc guarantees.
stephen-crawford marked this conversation as resolved.
Show resolved Hide resolved
- `@opensearch.experimental`: Mark rapidly changing [experimental code](./DEVELOPER_GUIDE.md#experimental-development).
stephen-crawford marked this conversation as resolved.
Show resolved Hide resolved
5. *Use sandbox for big core changes*: Any new features or enhancements that make changes to core classes (e.g., search phases, codecs, specialized lucene APIs) are more quickly merged if they are sandboxed. This can only be enabled on the java CLI (`-Dsandbox.enabled=true`)
6. *Micro-benchmark critical path*: This is a lesser known mechanism, but if you have critical path changes you're afraid will impact performance (gc, heap, direct memory, CPU) then including a [microbenchmark](https://github.com/opensearch-project/OpenSearch/tree/main/benchmarks) with your PR (and jfr or flamegraph results in the description) is a *GREAT IDEA* and will help expedite the review process.
7. *test, test, test*: pretty self explanatory ([OpenSearchTestCase](./test/framework/src/main/java/org/opensearch/test/OpenSearchTestCase.java) for unit tests, [OpenSearchIntegTestCase](./test/framework/src/main/java/org/opensearch/test/OpenSearchIntegTestCase.java) for integration & cluster tests, [OpenSearchRestTestCase](./test/framework/src/main/java/org/opensearch/test/rest/OpenSearchRestTestCase.java) for testing REST endpoint interfaces, and yaml tests with [ClientYamlTestSuiteIT](./rest-api-spec/src/yamlRestTest/java/org/opensearch/test/rest/ClientYamlTestSuiteIT.java) for REST integration tests)
stephen-crawford marked this conversation as resolved.
Show resolved Hide resolved

In general, the more guardrails you add to your change, the higher the chance your PR is merged quickly. We can always relax these guard rails in smaller followup PRs. Reverting a GA feature is much more difficult. Check out the [DEVELOPER_GUIDE](./DEVELOPER_GUIDE.md#submitting-changes) for more useful tips.

## Troubleshooting Failing Builds
dblock marked this conversation as resolved.
Show resolved Hide resolved

The OpenSearch testing framework offers many capabilities but exhibits significant complexity (it does lot of randomization internally to cover as many edge cases and variations as possible). Unfortunately, this posses a challenge by making it harder to discover important issues/bugs in straightforward way and may lead to so called flaky tests - the tests which flip randomly from success to failure without any code changes.
The OpenSearch testing framework offers many capabilities but exhibits significant complexity (it does lot of randomization internally to cover as many edge cases and variations as possible). Unfortunately, this posses a challenge by making it harder to discover important issues/bugs in straightforward way and may lead to so called flaky tests - the tests which flip randomly from success to failure without any code changes.
stephen-crawford marked this conversation as resolved.
Show resolved Hide resolved

If your pull request reports a failing test(s) on one of the checks, please:
stephen-crawford marked this conversation as resolved.
Show resolved Hide resolved
- look if there is an existing [issue](https://github.com/opensearch-project/OpenSearch/issues) reported for the test in question
- if not, please make sure this is not caused by your changes, run the failing test(s) locally for some time
- if you are sure the failure is not related, please open a new [bug](https://github.com/opensearch-project/OpenSearch/issues/new?assignees=&labels=bug%2C+untriaged&projects=&template=bug_template.md&title=%5BBUG%5D) with `flaky-test` label
- add a comment referencing the issue(s) or bug report(s) to your pull request explaining the failing build(s)
- as a bonus point, try to contribute by fixing the flaky test(s)
- look if there is an existing [issue](https://github.com/opensearch-project/OpenSearch/issues) reported for the test in question
- if not, please make sure this is not caused by your changes, run the failing test(s) locally for some time
- if you are sure the failure is not related, please open a new [bug](https://github.com/opensearch-project/OpenSearch/issues/new?assignees=&labels=bug%2C+untriaged&projects=&template=bug_template.md&title=%5BBUG%5D) with `flaky-test` label
- add a comment referencing the issue(s) or bug report(s) to your pull request explaining the failing build(s)
- as a bonus point, try to contribute by fixing the flaky test(s)
-
Loading