What changes are considered breaking

Dev
#1

We don’t allow breaking changes in our patch releases, but we have not fully defined what we consider as Breaking. Both @Paras and @abhimanyusinghgaur have asked how they can identify what changes are considered Breaking. I am asking input from support and engineering. Please add your comments here by the end of this week. I will then convert this into a wiki page.

Here is conclusion/summary taken from comments:

We consider these breaking changes:

  1. Any user/client facing incompatible configurations changes via CLI, UI, Rest API request/responses.
  2. Non Backwards compatible change in propreitery formats for snapshots, backups/restores, p/w/zw dirs etc.
  3. Log format/message changes specially the Error/ Warn levels or v1 level (debatable).
  4. Changes to defaults whether it is behavior or configurations.
  5. Any incompatible changes to the GraphQL±, GraphQL query languages.

Questions to ask before deciding:

  1. Can i stop an older dgraph and then start a newer dgraph in the same directory (with the same configuration, and without downtime)? If not, it’s a breaking change.
  2. Can I run a cluster having a mix of the older dgraph and the newer dgraph, at least for a few hours while my systems upgrade? If not, it’s a breaking change
  3. Is there any API which will no longer work, or returns different results (no matter how small the difference is)? If so, it’s a breaking change. The only exception is if the old version did not work as documented. In that case, this may not be considered a breaking change.
  4. Can i roll back from the newer dgraph to an older dgraph by stopping and starting dgraph? If not, it’s a breaking change as well, though this category of changes may be acceptable to release.
  5. Does this PR “need” to go into the last major release? Or, can it wait for the next major release? A “need” is established by a PR which fixes a crash failure for e.g. It is going to affect users of the major release, so they need this PR for stability.
#2

From what I understand, breaking changes are the ones where a particular functionality changes on how it is used or is removed from the previous version. Upgrades from a previous version to the new version will result in that functionality not working as before.

Some examples,

  1. Any user/client facing incompatible configurations changes via CLI, UI, Rest API request/responses.
  2. Non Backwards compatible change in propreitery formats for snapshots, backups/restores, p/w/zw dirs etc.
  3. Log format/message changes specially the Error/ Warn levels or v1 level (debatable).
  4. Changes to defaults whether it is behavior or configurations.
  5. Any incompatible changes to the GraphQL±, GraphQL query languages.
1 Like
#3

I am not sure about this. But in some cases users also depend on the error message we send, as part for any request. Hence change in error message can also be considered as breaking change.

#4

Consider this: In K-shortest path queries we were not excluding cycles from our output paths. This was not intended behavior but a bug. After fix we explicitly exclude cyclic paths from our output. Output format remains same but output paths can change for some queries. Would this be considered a breaking change?

#5

That is a bug. I wouldn’t consider it breaking.

1 Like
#6

I would consider what @Anurag mentioned as a breaking change. We couldn’t be sure someone wasn’t relying on that functionality. That said, we shouldn’t be shy to merge such changes to the next major release, as we believe the earlier functionality was incorrect, but we shouldn’t update that in a patch.

Other than the points that Paras Mentioned, I’d consider these rules of thumb.

  • Can i stop an older dgraph and then start a newer dgraph in the same directory (with the same configuration, and without downtime)? If not, it’s a breaking change.
  • Can I run a cluster having a mix of the older dgraph and the newer dgraph, at least for a few hours while my systems upgrade? If not, it’s a breaking change
  • Is there any API which will no longer work, or returns different results (no matter how small the difference is)? If so, it’s a breaking change. The only exception is if the old version did not work as documented. In that case, this may not be considered a breaking change.

More advanced:

  • Can i roll back from the newer dgraph to an older dgraph by stopping and starting dgraph? If not, it’s a breaking change as well, though this category of changes may be acceptable to release.
2 Likes
#7

I agree with what Paras has mentioned.

I had this change where some HTTP and GraphQL APIs would start requiring auth as compared to their previous versions. I think this should be a breaking change as it would force users to update their application code in order to make use of those APIs again.

#8

Agree with @gja.

One more way to think about it is – does this PR “need” to go into the last major release? Or, can it wait for the next major release? A “need” is established by a PR which fixes a crash failure for e.g. It is going to affect users of the major release, so they need this PR for stability. But, the “breaking fix” that @Anurag has, that behavior has been there for a while, and does NOT need to go into the last major release.

1 Like