[RFC] What is a breaking change in OpenSearch Dashboards?

[davidlago]

Coming from a discussion in our latest community meeting, it seems like we might not have a clear definition understood by all participants of what constitutes a breaking change (which will necessitate a major version bump). What are the APIs and contracts that we are officially supporting? what is everything else?

A couple of questions that hopefully will get this RFC going:

• Would a major version bump of Angular constitute a breaking change?
• Would Angular's removal? (see [Initiative] Remove AngularJS as dependency #1560)
• How about a NodeJS major version bump?
• What is the interface we offer to plugins, that if broken would constitute a breaking change?
• How about user experiences? Would a major redesign (see [RFC] Future Vision for Dashboards #4298) constitute a breaking change as we are "breaking" habits and established user workflows?

The outcome of this RFC should be a decision on what we consider a breaking change, that then we can put out there in the website/repos/other and reference when making these kind of decisions. This will also inform users and help them understand the level of risk when building on assumptions that are not considered part of the declared interface, as those will be subject to change without being considered breaking.

[kgcreative]

I'm also curious as to what are considered breaking in terms of visual changes.

• Would changing the current theme considered breaking?
• Would making significant changes to a front-end component considered breaking?
• Would upgrading a major version of the UI library considered breaking, specifically if there are component changes? (For example, changing a default value in a component in order to cascade a wanted change through the application)

[seraphjiang]

these are good questions, looks like community would love to get clarification.
Should we change the issue to Questions instead of request for comment typically that include a proposal with a few options.

[ashwin-pc]

Firstly thanks for bringing up the topic @davidlago, this is a conversation ive been wanting to have for a while. To talk about breaking change we need to talk about semver as a whole though. Dashboards today is not semver compliant. This does not mean that dashboards introduces breaking changes, but it does not comply with the sever spec, particularly the first requirement for semver:

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive.

So what is it that OSD follows today? Here's my current understanding:

• No change that breaks a dependent plugins experience due to a change in the available API's is introduced in a minor version bump.
• Today we consider even direct npm dependencies to be included as a part of this.

This being said this is a half measure and we should simply comply with the semver spec. Questions like this are addressed by the spec and is also a widely adopted spec in software development. As @seraphjiang proposed, I would like to hear proposals for what the public api that Dashboard supports should be.

[AMoo-Miki]

IMO:

• Would a major version bump of Angular constitute a breaking change?
  A major bump to a direct dependency that doesn't include a change in its APIs (ie, won't require plugins to make code changes) shouldn't be a breaking change. Granted that it forces them to update their package.json but that kind of change is done with every release of OSD.

• Would Angular's removal? (see [Initiative] Remove AngularJS as dependency #1560)
  OSD dropping a dependency shouldn't matter to plugins who must declare their own deps in their package.json; after OSD drops it, their newly compiled bundle will be bigger than before to include Angular.

• How about a NodeJS major version bump?
  With the latest changes where Node.js was bumped and users were allowed to run any version between 14-18, we have tried to make sure OSD continues to function using Node 14 while also functioning with the newer ones. In some places this has been via adding conditions dependent on Node version. OSD has to continue this and only remove those conditions when a major release is made. If such extra steps are not taken to remain compatible with the original version of Node that OSD was released with, it is a breaking change.

• What is the interface we offer to plugins, that if broken would constitute a breaking change?
  OSD will have to define and publish this.

• How about user experiences? Would a major redesign (see [RFC] Future Vision for Dashboards #4298) constitute a breaking change as we are "breaking" habits and established user workflows?
  As long as users are offered a way to go back to the previous experience, I wouldn't call it a breaking change. I think habit breaking UX should be a breaking change but the definition of habit-breaking should be crystal clear.

[ZilongX]

A change in one part of a software system that potentially causes other components to fail. as Wiki said :)

My $0.0.2 :

• As long as the changes being made are backward-compatible, then it's not a breaking change. Based on what the Angular version bumping (including the removal of AngularJS aka Angular 1.x) would not be breaking changes since our public APIs are not changed
• Also one big reason for upgrading the framework/runtime like Angular/NodeJS is to keep up of the latest security standard, which honestly should be picked up as soon as available and stable.
• User experiences wise also don't think we should hold the new shining presence until a major bump. Maybe we can add a back to old presence button though in case users don't like the new look and would prefer to stay the old classic way.
• Plus our current major version bump strategy seems not quite clear, are we just waiting for the accumulation of new features (breaking changes lol) to be enough , or maybe we can try the nodejs way aka release a major version every six months (longer or shorter)

Also based on my own exp, just blocking a dependency bump for CVE fixes due to it has breaking changes (while actually it doesn't impact our public APIs) is truely painfulllll ლ(ﾟдﾟლ)

[AMoo-Miki]

Here are two questions to the community of users and developers:

1. If you were a plugin developer, how would you feel if Dashboards bumps a direct dependency where you are forced to make code changes in your plugin? Would you consider that a breaking change? Would you feel differently if that bump was security related?

2. As a user of Dashboards, would you be comfortable upgrading to a new major version of Dashboards just because some dependency was bumped which adds nothing to your experience? Would you feel differently if the version you are on gets no new features (as new features only go into the current major version) and only the previous major version gets security-related fixes?

[ashwin-pc]

As long as the changes being made are backward-compatible, then it's not a breaking change. Based on what the Angular version bumping (including the removal of AngularJS aka Angular 1.x) would not be breaking changes since our public APIs are not changed

@ZilongX but what is the public API? Is it defined somehwere?

[wbeckler]

2. (as new features only go into the current major version)

@AMoo-Miki I think you meant "minor version." Under semver, breaking changes are major (1.x - > 2.x), features are minor (2.8 -> 2.9), and bug fixes are patches (2.8.0 -> 2.8.1).

[ananzh]

I think we are discussing two definitions:

Loose definition

A breaking change is defined more broadly as any modification that alters the user experience in a substantial way.

Pros

• Prioritize user security and experience
• Reduce restrictions on updating and integrating new dependencies, promoting flexibility and progress.
• Encourages plugin developers to actively maintain and update their plugins to align with the latest platform standards.

Cons

• May cause frequent disruptions for plugin developers

A bit tighter defintion

A breaking change is defined as any modification that directly breaks the functionality of plugins.

Pros

• Minimize disruptions for plugin developers by ensuring compatibility with existing plugins.
• Create a more stable development environment.
• Could potentially encourage more plugin development??

Cons

• Might slow down the adoption of new features and improvements due to concerns over plugin compatibility.
• Verification of impact on all plugins, especially external ones, can be challenging.
• Could lower the platform's security standard.

I think we should let our customers to decide their priorities, be it maintaining the use of certain plugins at an older OSD version maybe due to some production concerns, or keeping their products at higher security standards. But we should provide them the options. This way we also provide plugin owners options, be it working on older OSD platform for their user concerns or developing newer versions to align with the latest platform standards.

[wbeckler]

@joshuarrrr created a definition in the context of a proposal to do an SDK that stabilizes the Dashboards interfaces for plugins. He pieces together several considerations that are worth looking at:

opensearch-project/opensearch-dashboards-sdk-js#41 (comment)

[davidlago]

Thanks for sharing, @wbeckler (and @joshuarrrr / @kavilla for the thoughts on that issue). It seems like several of the points hinge on the explicit definition of a contract (either via formal API/SDK specs, or explicit documentation). If the result of this RFC is that we come out the other end with just that, being more explicit about what the contract looks like, in my book that's a win. This is captured in the last 2 questions from the top of this issue:

• What is the interface we offer to plugins, that if broken would constitute a breaking change?
• How about user experiences? Would a major redesign (see [RFC] Future Vision for Dashboards #4298) constitute a breaking change as we are "breaking" habits and established user workflows?