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

Clarify plugin repo naming conventions #27

Merged
merged 1 commit into from
Mar 22, 2022
Merged
Changes from all 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
33 changes: 26 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't love the name "Official". How about "Plugins Released with OpenSearch", of which there are 2 kinds, native and non-native?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was following naming pattern from InstallPluginCommand.java, see the JavaDoc and var name (also in online docs). Shall we rename in the install tool source code as well?

I would use "Native" and "Thirdparty" plugins. WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. That can be a separate PR. Let's leave it this way here, consider following up?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider following up?

Yes, naming should be addressed in different PR.


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

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Copyright OpenSearch Contributors. See [NOTICE](NOTICE.txt) for details.