[RFC] Clarifying Semantic Versioning for OpenSearch Dashboards

[ashwin-pc]

Summary

This RFC proposes a refined Semantic Versioning (SemVer) policy for OpenSearch Dashboards. It explicitly separates internal npm dependencies from the semver public contract, reduces the likelihood that internal changes will cause breaking version bumps, and provides examples illustrating when a dependency update affects the public API (and thus semver) versus when it does not.

Background

OpenSearch Dashboards currently treats many aspects of its platform—including npm dependencies, server APIs, and the UI—as part of its semver contract. In particular:

• Plugin Dependencies: Plugins share many core npm dependencies with the platform. Upgrading or changing a dependency version can cause plugin authors to modify their implementations, even if the public contract remains untouched.
• Server APIs: The server exposes documented APIs used by plugins and external consumers.
• UI Changes: Significant UI updates have also been considered potentially breaking, though the criteria for what qualifies as a breaking UI change is not always clear.
  This broad interpretation of what counts as a semver-breaking change has made it difficult to address security fixes and internal improvements without triggering a major version increment.

Motivation

1. Security Fixes Without Major Releases: Enable prompt patching of vulnerabilities without forcing plugin developers to react to an unnecessary major version bump.
2. Clear Separation of Internal vs. Public: Provide explicit guidance to distinguish changes that affect external plugin authors or users from internal implementation details.
3. Predictable Release Cycles: Reduce friction and confusion for plugin maintainers, ensuring that semver-breaking updates only occur when a documented public interface truly changes.
4. Better Communication: Clarify what “public contract” means, so contributors and users know precisely which changes are considered breaking, minor, or patches.

Proposal

1. Defining the Public Contract

Principle: A “public contract” is any interface or behavior that is:

• Documented:
  Covered in official documentation or API references explicitly intended for external consumption (e.g., plugin APIs, server endpoints).
• Stability-Promised:
  Declared stable and supported across releases unless a deliberate version bump is communicated.
• Externally Consumed:
  Relied upon by third-party developers or users, such that any change would require them to alter their code or workflows.
• Impactful When Altered:
  Modifications would force external consumers to update their implementations or significantly change their usage patterns.

Public Contract Checklist

Ask these questions when determining if a change affects the public contract:

1. Is it explicitly documented as part of our public API or UI behavior?
2. Is it intended for and used by plugin developers or end users (externally)?
3. Would a change force external consumers to adjust their code or workflows?
4. Have we promised stability for it across releases?
   If all answers above are “yes,” changes to that interface are semver-breaking. Otherwise, the change can be classified as internal.

2. Excluding npm Dependencies from Semantic Versioning

Because of the coupled architecture, npm dependencies are often shared between OpenSearch Dashboards and its plugins, causing updates to affect plugin builds. This policy explicitly excludes npm dependency changes from semver unless they alter a documented, stable public interface.

1. Internal vs. Public Impact:
   • Internal Updates: Any upgrade or addition to npm dependencies that does not alter a documented API or plugin interface is considered an internal change.
     Example: Upgrading from lodash@4.17.20 to lodash@5.0.0 to address a security fix. The plugin API or behavior doesn’t change, so this is not a breaking change.
   • Public Interface Changes: If a dependency upgrade does modify a documented function, endpoint, or behavior on which plugins rely, it is a breaking change.
     Example: Migrating from lodash@4 to lodash@5 means that we cannot support a data plugin API that directly exposes a lodash API that changes with the version upgrade
2. Handling New Dependencies: When core introduces a new npm dependency that plugins might already use, it is not considered breaking unless it forces changes in the documented public interface.

Objective: Decouple the semver contract from routine npm dependency updates, so only true API/behavioral changes trigger a major version bump.

3. Versioning Rules

OpenSearch Dashboards adopts Semantic Versioning 2.0.0 with the following structure:

• Major Version (X): Introduces breaking changes to the documented public contract (e.g., plugin APIs, server APIs, or UI behaviors that are explicitly supported).
  • Deprecations planned for removal can also occur here.
• Minor Version (Y): Adds new, non-breaking features or enhancements to the public contract.
  • Includes additions to server APIs, new plugin APIs, or UI enhancements that do not disrupt existing usage.
• Patch Version (Z): Contains backward-compatible bug fixes, security patches, or internal improvements.
  • Npm dependency upgrades that do not alter the public contract fall into this category.

4. UI Versioning Considerations

While UI changes can sometimes be disruptive, the RFC distinguishes:

• UI as a Public Contract: If the UI includes documented user experiences or extension points (e.g., plugin injection points, UI event hooks), then changes to these behaviors are considered breaking.
• Cosmetic or Minor Changes: Layout or style updates that do not affect documented plugin interactions or user workflows should be classified as internal, and thus only require a patch or minor release if they are purely additive.

5. Deprecation Policy

To provide clarity on when features or interfaces will be removed:

1. Announce Deprecation: Clearly mark deprecated features in release notes, documentation, and console/log warnings.
2. Provide a Timeline: Maintain support for deprecated features for at least one minor release cycle before removal in the next major version.
3. Migration Guidance: Offer instructions on how to transition away from deprecated features.

6. Implementation Plan

Once this RFC is closed we can add a SEMVER.md file in the repository to outline these rules, including the examples of internal vs. public changes.

Feedback required

The feedback that this RFC is looking for is

1. Feedback from plugin developers, end users, and maintainers on the proposed policy
2. Use cases to further refine the guidance around “public contract” boundaries

[kavilla]

Makes sense:

Is there a designated location we are planning where the public contract is documented and maintained? I see the SEMVER.md is an examples.

What is the process for determining if a change affects the public contract? And can plugins proposed something is a public contract or will it be only maintainers that determine the public contract. Will there be a regular review on the public contract?

For breaking changes as a maintainer, do we have a process? Should we get agreement among stakeholders or just maintainers that this breaking change makes sense? We should also label the PR with the breaking change label so it's easier to find these PRs at the time of major version release.

Should we have policies on deprecation and timelines? Since we have a lot of long running deprecated stuff.

[seraphjiang]

i like the idea to remove treating npm/internal change as breaking

About doc:

regarding doc, we already using openapi to doc doc, we should continue to use it for all existing public api and new api

https://github.com/opensearch-project/OpenSearch-Dashboards/tree/9ecb66d46c7f07209db8076987fa4d2771379c71/docs/openapi

About dependencies/interface
as a frontend project, I would like to see we clarify what does UI behavior as contract mean.
what i mean, we should specific call out the global CSS, global variable, code level interface, public rest api, as well as key dependencies like Oui

about versioning Rules,
it should be suggested, but not mandatory, as far as today, OSD version bump up regardless major/minor/patch is driven by OpenSearch release instead of OSD's own need.
distribution is binded with OpenSearch, that means, even if there is no any change, we have to bump up OSD version. we should also address this in our roadmap. #9192

while the rfc is aim to discuss Semantic Versioning for OSD, from content it is mainly focus on developer's view, while we should be open to bump up version for new feature and change that don't introduce any break change.

[ashwin-pc]

Is there a designated location we are planning where the public contract is documented and maintained? I see the SEMVER.md is an examples.

@kavilla Yes we will have a single place where this is documented. I think as @seraphjiang mentioned, the openapi doc has already been started, we will need to add to that. We can also just specify for now in a api.md file what the API's are and link to the openAPI docs where it makes sense.

What is the process for determining if a change affects the public contract? And can plugins proposed something is a public contract or will it be only maintainers that determine the public contract. Will there be a regular review on the public contract?

This will be defined in the semver.md file which requires approvals from maintainers before its changed

For breaking changes as a maintainer, do we have a process? Should we get agreement among stakeholders or just maintainers that this breaking change makes sense? We should also label the PR with the breaking change label so it's easier to find these PRs at the time of major version release.

Thats not something i want to cover here. This is just to clarify the semantic versioning definition for OSD. The process to enforce it can come later. Lets make sure we agree on the definition first.

Should we have policies on deprecation and timelines? Since we have a lot of long running deprecated stuff.

I have a section on that inthe RFC

---

as a frontend project, I would like to see we clarify what does UI behavior as contract mean.
what i mean, we should specific call out the global CSS, global variable, code level interface, public rest api, as well as key dependencies like Oui

Good callout. I can add that

about versioning Rules,
it should be suggested, but not mandatory, as far as today, OSD version bump up regardless major/minor/patch is driven by OpenSearch release instead of OSD's own need.
distribution is binded with OpenSearch, that means, even if there is no any change, we have to bump up OSD version. we should also address this in our roadmap. #9192

I agree on following OpenSearches definitions. Opensearch also follows senver2.0. I just restated them given that we are discussing semver here. I can remove it too. As for the roadmap. I dont want to mix the conversations. I agree with the other proposal to allow different versions but that can happen independent of this change.

while the rfc is aim to discuss Semantic Versioning for OSD, from content it is mainly focus on developer's view, while we should be open to bump up version for new feature and change that don't introduce any break change.

What version do you want us to be open about bumping up? That wasnt clear to me

[virajsanghvi]

1. Defining the Public Contract

Is it intentional that this definition doesn't cover UI itself?

Public Contract Checklist
Would a change force external consumers to adjust their code or workflows?

Is it always clear what is being consumed? Should default assumption be that it is consumed?

2. Excluding npm Dependencies from Semantic Versioning

How are plugins bound by OSD's npm dependencies? In what situation will OSD fail to build when dependencies are mismatched. There's a tension that Plugins may depend on a npm package version for particular logic, but are at the same time bound to the same version that OSD uses. If OSD updates the package, it potentially could be problematic for the plugin, and while the plugin probably shouldn't have depended on that functionality, they also didn't really have a choice in the versioning. I think we should at least call this out as a risk for plugins, and would be good to understand how we can further mitigate (not clear on what packages this would be an issue for).

UI as a Public Contract: If the UI includes documented user experiences or extension points (e.g., plugin injection points, UI event hooks), then changes to these behaviors are considered breaking.

Extension points are code, right? They don't need to be called out from a UI perspective, right?

Documented user experiences is quite broad. What does "documented" mean and what "changes to these behaviors" are considered breaking. Are we saying the functionality that is documented is breaking, but the UX can change? Is some amount of UX consistency expected? Agree that getting more specific per seraphjiang will help.

For breaking changes as a maintainer, do we have a process?

Saw you said we'd define later, but would be good to have a way to ensure correct calibration.

[ashwin-pc]

@virajsanghvi :

Is it intentional that this definition doesn't cover UI itself?

Yes, The UI itself can be interpreted as literally any change on the UI even if it does not impact the user. By being explicit we make sure we leave ourselves freedom to fix the things that we think are good while also ensuring that things that we think should not change are explicitly written down and agreed upon.

Is it always clear what is being consumed? Should default assumption be that it is consumed?

We need to be explicit about whats consumed. Thats the goal of the SEMVER.md file i will raise if we agree to this. The default assumption is that its not consumed. Some basic defaults can be assumed to be consumed though like plugin start and setup menthds, exports, api. The rest are implicitly assumed not part of the public contract

How are plugins bound by OSD's npm dependencies? In what situation will OSD fail to build when dependencies are mismatched. There's a tension that Plugins may depend on a npm package version for particular logic, but are at the same time bound to the same version that OSD uses. If OSD updates the package, it potentially could be problematic for the plugin, and while the plugin probably shouldn't have depended on that functionality, they also didn't really have a choice in the versioning. I think we should at least call this out as a risk for plugins, and would be good to understand how we can further mitigate (not clear on what packages this would be an issue for).

I agree and this is the main reason we hesitated against updating dependencies. However what the last few years have thought us is that either we agree that this is an okay tradeoff to be on top of CVE's and other dependency related bottlenecks, or slow down or use hacky work arounds to build the features and fix CVE's (e.g. forking public npm repos and hostign them under our personal npm accounts). There my argument is for making the tradeoff for speed

Extension points are code, right? They don't need to be called out from a UI perspective, right?
Documented user experiences is quite broad. What does "documented" mean and what "changes to these behaviors" are considered breaking. Are we saying the functionality that is documented is breaking, but the UX can change? Is some amount of UX consistency expected? Agree that getting more specific per seraphjiang will help.

Yeah let me get back on something more specific here. My intention was that there will be no change from how we treat UX changes right now. But how we treat it today is also a grey area. I will clarify this more

For breaking changes as a maintainer, do we have a process?
Saw you said we'd define later, but would be good to have a way to ensure correct calibration.

My idea here was to have essentially a tiered system of reviews for changes. A few core maintainers with different expertise's are required for breaking change reviews. Then we have area specific maintainers who's review is required for changes that impact that area. Smaller changes can be reviewed by any maintainer. Does this answer that question @kavilla @virajsanghvi ?

[virajsanghvi]

Is it always clear what is being consumed? Should default assumption be that it is consumed?

We need to be explicit about whats consumed. Thats the goal of the SEMVER.md file i will raise if we agree to this. The default assumption is that its not consumed. Some basic defaults can be assumed to be consumed though like plugin start and setup menthds, exports, api. The rest are implicitly assumed not part of the public contract

How do we know something is consumed? Is consumption defined as consumed within opensearch-project? If its just best effort, it just brings into question the default assumption being not consumed.

For breaking changes as a maintainer, do we have a process?
Saw you said we'd define later, but would be good to have a way to ensure correct calibration.

My idea here was to have essentially a tiered system of reviews for changes. A few core maintainers with different expertise's are required for breaking change reviews. Then we have area specific maintainers who's review is required for changes that impact that area. Smaller changes can be reviewed by any maintainer. Does this answer that question @kavilla @virajsanghvi ?

That's fine, my main ask was just that we need to write this down and flesh it out. Even having tiers brings up the question of who assigns tiers. Fine not to do it as part of this RFC, but think we need it asap in order to be successful here.

[AMoo-Miki]

As a maintainer, I appreciate the effort put into refining the SemVer policy for OSD. While the proposal addresses key topics, there are areas that need some clarification and refinement.

1. Defining the Public Contract
   This is a strong start but needs more specificity.

2. Process for Determining Breaking Changes
   The RFC should prioritize identifying who is affected by breaking changes before defining what constitutes a breaking change. By categorizing stakeholders (end users, admins, plugin developers) and tailoring definitions and processes to their needs, the RFC can ensure more comprehensive and predictable versioning policies.

   The RFC assumes that a change is only breaking if it alters a documented public interface or behavior. However, this assumption may not hold for all stakeholders:

   1. End Users: Even undocumented UI behaviors can become de facto standards if widely relied upon. Also, UI layout changes can disrupt workflows or alter documented user experiences, which are critical for end users.
   2. Admins: Configuration or deployment changes might not be explicitly documented but can still have significant impact.
   3. Plugin Devs: Any change requiring plugin developers to modify their code or dependencies is inherently breaking for this group. Undocumented APIs which have been relied upon due to lack of alternates can become de facto standards too.

   Suggestion: The RFC could benefit from explicitly identifying stakeholders and tailoring its definitions accordingly.

   1. End Users: Define clear criteria for breaking UI changes, including examples of both breaking and non-breaking scenarios (more below).
   2. Admins: Come up with guidelines for assessing whether platform-level changes are breaking for admins.
   3. Plugin Devs: Eliminate the friction caused by deps (more below).

3. UI Versioning Considerations
   Regarding UI changes, while "cosmetic or minor changes" are excluded, it is unclear what is considered a "documented user experience" or "extension point". Are global CSS variables considered public contracts? What about UI layout structures, navigation patterns, or anything that changes workflows but don't affect documented functionality? Changing colors could break branding; how much change is considered a breaking change? On a side note, I think "extension points" are code-level interfaces and shouldn't be discussed in UI.

   Suggestion: OSD needs to have an explicit list of UI elements that are part of the public contract. OSD also needs to provide clear examples of breaking vs non-breaking UI changes to guide contributors. A regular review process needs to be created to audit the interfaces for potential reclassification as public or internal.

4. Excluding NPM Dependencies from Semantic Versioning
   I can't remember if we did something to avoid hoisting deps of plugins, even if they are shared with OSD. This needs to be experimented with to see if it is still a problem. OSD has always assumed that if a plugin uses a different version of a dep, the plugin will break or it will break OSD; I am not sure how true that was then or is now. The single-version enforcement is purely a self-imposed limitation and we would have to understand better what could happen if we don't impose that limitation.

   If we cannot remove the self-imposed single-version policy completely, excluding NPM deps from SemVer introduces risks for plugin developers who have to compile and release a new version for even patch releases of OSD that bump a dep to fix a bug. In other words, OSD adhering to SemVer or not makes no difference to plugin devs, since they have to make a new release even for the smallest of changes in the deps. The "loose" policy was meant to be a stopgap while we figure out if we can get rid of single-version completely.

   In the past, there have been plugins that relied on an OSD dep without declaring that dependency themselves. I consider this a very wrong practice and have no sympathy for the plugins that break if OSD excludes NPM deps from SemVer. However, I feel for the administrators and users who chose to rely on those plugins.

   Suggestion: Get rid of single-version policy completely - not just default to loose but eliminate the need for it completely. No plugin should rely on OSD's deps nor be forced into a version imposed by OSD. Doing so, we won't even need to think about NPM deps and Semver.

5. Versioning Rules
   The versioning rules for OpenSearch Dashboards are tied to OpenSearch releases, even if no breaking changes occur in Dashboards itself. This creates unnecessary version bumps that may confuse users.

   Suggestion: While I don't think this will be a "problem" in the near future, or ever, it would be best to continue exploring decoupling OSD and OS.

---

Thanks Ashwin for starting this conversation.

[ashwin-pc]

Linking an older discussion around this as well. #4416