This document lists down the standards for OpenSearch plugins which can be used by plugin authors.
Follow these best practices while developing any plugin.
Make sure your plugin follows the SoC design principle and has different functionality organized as separate entities. Each component in the plugin should have a singularity of purpose which would then make the over-all plugin easier to maintain. If each component focusses on a single purpose it is easier to reuse that in other plugins with different contexts. Also ensure the component follows the best practise of encapsulation by having well-defined interfaces.
Make effective use of namespacing since it will allow co-existence of ambiguous names / classes with the same name and help avoid collisions.
Code styling is done with Spotless.
To use Spotless:
- Add Spotless plugin in build.gradle.
- Format Java files with the Eclipse JDT (Java Development Tools) formatter, using the Spotless Gradle plugin. Sample formatting rules can be found here.
Please follow these formatting guidelines:
- Java indent is 4 spaces
- Line width is 140 characters
- Lines of code surrounded by
// tag::NAMEand// end::NAMEcomments are included in the documentation and should only be 76 characters wide not counting leading indentation. Such regions of code are not formatted automatically as it is not possible to change the line length rule of the formatter for part of a file. Please format such sections sympathetically with the rest of the code, while keeping lines to maximum length of 76 characters. - Wildcard imports (
import foo.bar.baz.*) are forbidden and will cause the build to fail. - If absolutely necessary, you can disable formatting for regions of code with the
// tag::NAMEand// end::NAMEdirectives, but note that these are intended for use in documentation, so please make it clear what you have done, and only do this where the benefit clearly outweighs the decrease in consistency. - Note that JavaDoc and block comments i.e.
/* ... */are not formatted, but line comments i.e// ...are. - There is an implicit rule that negative boolean expressions should use the form
foo == falseinstead of!foofor better readability of the code. While this isn't strictly enforced, if might get called out in PR reviews as something to change.
Make sure to use the asynchronous method invocation which avoids the calling thread to not block while waiting for a response. You can make effective use of callbacks for retrieving the results and parallelly process multiple independent tasks.
Make sure to validate all the user input before it is processed by the backend. For example, APIs that contain data in its body should have the data validated so that no malicious or invalid data is sent along with the API.
API Versioning provides the support for the producers to incorporate latest changes in a new version of the API while also making sure that the consumers still have access to the older version of the API.
Log different events at accurate severity levels and thereby preventing excessive logging. Use a good logging framework which provides the support for multiple severity levels, setting up different appenders which provide support for lossy and log summarizing appenders.
Create a Github Actions workflow to check for broken links in text files (.md, .html, .txt, .json) on pull requests and push. See .github/workflows/links.yml for an example.
See lycheeverse/lychee-action for more information.
CI Workflows should be setup to run and verify plugin unit, integration and backwards compatibility tests. Workflows should run on main and release branches including pull requests merging into them.
Example: See CI Workflow in anomaly-detection.
Code coverage reporting can be found at TESTING.md.
License Header details can be found at HEADERS.md.
For all new features and functionality, changes for every release should update the documentation via documentation-website.
Public documentation can be found on OpenSearch website.
Release notes for plugins can be found at RELEASE_NOTES.md.