Where should we put plugin migration instructions?

We are starting to migrate many plugins and are looking for a place to share guides, experiences, and best practices. Where shall we put it? This would be nuts and bolts for developers.

Some ideas:

  • MIGRATING.md on GitHub opensearch-project/OpenSearch and opensearch-project/OpenSearch-Dashboards
  • MIGRATING_PLUGINS.md on GitHub opensearch-project/OpenSearch and opensearch-project/OpenSearch-Dashboards
  • A single new repo for called migrating-plugins with a README.md.

What do you think?

Add a point here - the same should be said for Dashboards - e.g. migrating from Kibana to OpenSearch Dashboards would have their own files in the the opensearch-project/OpenSearch-Dashboards

I like the new repo option Community-Plugins with a MIGRATING_PLUGINS.md in it.

There is currently an enhancement request for a community repo but, personally, I don’t think these docs belong in that repo (mixing nuts-and-bolts with more organizational info doesn’t make sense).

Additionally, multiple community repos might be confusing. So maybe we stay away from community in the repo name. (Personal opinion)


Good point, I edited the original text to clarify that if we go with MIGRATING we would have 2 sets in OpenSearch and OpenSearch-Dashboards.

I like the idea of having MIGRATING.md in a dedicated repo.
It allows to talk about all things plugins which might be lost or tangled if it is in the main fork repos.
It also helps to have all questions(issues) in one place.

Thinking about the future, migrating will just be for may be couple of years and later this would probably be the home on how developers can build plugins. If we can make the repo name more generic it would be great. I can’t think of any better names :thinking:, may be OpenSearch-plugins?

This would be a great place to collaborate on plugin tools as well. Like common test cases for instance.
I already have an issue migrating the basic plugin for the blog post :man_facepalming:

I think this is a good name, at this point we just need a place to collaborate :slight_smile:

I created a perl script to do more of class/namespace/package renaming in automatic.
I tested on the flattened plugin. I attached it here: "flattened" type with OpenDistro - #9 by aparo
I can simply changed in a python script that automatically can code/files rename.

I like OpenSearch-plugins!

Hey – as long as we’re committed to adding tools, examples, etc I’m okay with creating a new single repo for all things plugins (Dashboards and OpenSearch Engine).

But if it’s just an MD file, a whole new repo seems like overkill to me :slight_smile:

Yeah the idea is to have examples, tools etc everything in one place.
This will include OpenSearch and OpenSearch Dashboards.

Ok looks like all of us agree that creating a new repo OpenSearch-plugins and start with README.md.
I will work to get the the new repo created and put in the migration information.

1 Like

Thats great. I did something similar, we could probably make it as a tool in the repo for the community.
Feel free to make a PR and we can improve it iteratively.

since everyone here is writing about migration i was just wondering: as long as the APIs of elasticsearch & opensearch stay more-or-less aligned: is there a way to build a plugin once for both and just have two separate packages? if so, could that be documented as well? i would presume that for now a lot of public plugin maintainers would want to target both platforms until they get a clearer picture on where their users are heading.

Thanks for pointing this out. In general, I agree that we need to do our best to make it really easy for plugin developers to write once and run on all versions. Either way there’s no talking about deprecating any APIs and if we ever do we’ll have to be extra careful.

So maybe we are being too eager in calling our files MIGRATING.md and it should be UPGRADING.md.

@ralph It’s not possible: the API are complitely different and have also different dependencies as JAR.

1 Like