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:
- Any user/client facing incompatible configurations changes via CLI, UI, Rest API request/responses.
- Non Backwards compatible change in propreitery formats for snapshots, backups/restores, p/w/zw dirs etc.
- Log format/message changes specially the Error/ Warn levels or v1 level (debatable).
- Changes to defaults whether it is behavior or configurations.
- Any incompatible changes to the GraphQL±, GraphQL query languages.
Questions to ask before deciding:
- 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.
- 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.
- 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.