From 79252f70dd18e6c9eff87523291a280422ecc9ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Vl=C4=8Dek?= Date: Fri, 25 Feb 2022 17:20:24 +0100 Subject: [PATCH] Clarify plugin repo naming conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OpenSearch plugins can "live" either inside the OpenSearch organization or outside it. This is the difference between official plugins and 3rd party plugins that are maintained in independent repositories. Currently, these two types of plugins are not recommended to share exactly the same repo naming conventions (this might change but not in the near-term future). If needed, the 3rd party plugin authors should also follow up with several extra checks in making sure the formal processes are correctly aligned with the community needs (such as Code of Conduct, Security Policy, Trademarks and Attributions). Closes #23 Signed-off-by: Lukáš Vlček --- README.md | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6e3f073..7ca8249 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) + - [Thirdparty 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.