diff --git a/README.md b/README.md index 6e3f073..e4e7b82 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ It comes packaged with: --- --- 1. [Create your plugin repo using this template](#create-your-plugin-repo-using-this-template) + - [Official plugins](#official-plugins) + - [3rd party plugins](#thirdparty-plugins) 2. [Fix up the template to match your new plugin requirements](#fix-up-the-template-to-match-your-new-plugin-requirements) - [Plugin Name](#plugin-name) - [Plugin Path](#plugin-path) @@ -30,13 +32,30 @@ Click on "Use this Template" ![Use this Template](https://docs.github.com/assets/images/help/repository/use-this-template-button.png) -Name the repository, and provide a description. We recommend using the following naming conventions: +Name the repository, and provide a description. + +Depending on the plugin relationship with the OpenSearch organization we currently recommend the following naming conventions and optional follow-up checks: + +### Official plugins + +For the **official plugins** that live within the OpenSearch organization (i.e. they are included in [OpenSearch/plugins/](https://github.com/opensearch-project/OpenSearch/tree/main/plugins) or [OpenSearch/modules/](https://github.com/opensearch-project/OpenSearch/tree/main/modules) folder), and **which share the same release cycle as OpenSearch** itself: + - Do not include the word `plugin` in the repo name (e.g. [job-scheduler](https://github.com/opensearch-project/job-scheduler)) - Use lowercase repo names - Use spinal case for repo names (e.g. [job-scheduler](https://github.com/opensearch-project/job-scheduler)) -- do not include the word `OpenSearch` or `OpenSearch Dashboards` in the repo name +- Do not include the word `OpenSearch` or `OpenSearch Dashboards` in the repo name - Provide a meaningful description, e.g. `An OpenSearch Dashboards plugin to perform real-time and historical anomaly detection on OpenSearch data`. +### Thirdparty plugins + +For the **3rd party plugins** that are maintained as independent projects in separate GitHub repositories **with their own release cycles** the recommended naming convention should follow the same rules as official plugins with some exceptions and few follow-up checks: + +- Inclusion of the words like `OpenSearch` or `OpenSearch Dashboard` (and in reasonable cases even `plugin`) are welcome because they can increase the chance of discoverability of the repository +- Check the plugin versioning policy is documented and help users know which versions of the plugin are compatible and recommended for specific versions of OpenSearch +- Review [CONTRIBUTING.md](CONTRIBUTING.md) document which is by default tailored to the needs of Amazon Web Services developer teams. You might want to update or further customize specific parts related to: + - **Code of Conduct** (if you do not already have CoC policy then there are several options to start with, such as [Contributor Covenant](https://www.contributor-covenant.org/)), + - **Security Policy** (you should let users know how they can safely report security vulnerabilities), + - Check if you need explicit part about **Trademarks and Attributions** (if you use any registered or non-registered trademarks we recommend following applicable "trademark-use" documents provided by respective trademark owners) ## Fix up the template to match your new plugin requirements @@ -102,10 +121,10 @@ Change all these path occurrences to match the path you chose for your plugin: Update the following section, using the new repository name and description, plugin class name, and plugin path: ``` -def pluginName = 'rename' // Can be the same as new repo name -def pluginDescription = 'Custom plugin' // Can be same as new repo description -def pathToPlugin = 'path.to.plugin' // The path you chose for the plugin -def pluginClassName = 'RenamePlugin' // The plugin class name +def pluginName = 'rename' // Can be the same as new repo name except including words `plugin` or `OpenSearch` is discouraged +def pluginDescription = 'Custom plugin' // Can be same as new repo description +def pathToPlugin = 'path.to.plugin' // The path you chose for the plugin +def pluginClassName = 'RenamePlugin' // The plugin class name ``` Next update the version of OpenSearch you want the plugin to be installed into. Change the following param: @@ -175,4 +194,4 @@ To view more complex CI examples you may want to checkout the workflows in offic This code is licensed under the Apache 2.0 License. See [LICENSE.txt](LICENSE.txt). ## Copyright -Copyright OpenSearch Contributors. See [NOTICE](NOTICE.txt) for details. \ No newline at end of file +Copyright OpenSearch Contributors. See [NOTICE](NOTICE.txt) for details.