Understand the versioning of our gems based on versioning/upgrades of dependency gems

[vishrutshah]

Team is having discussion around the best practices on dependency packages of our Ruby packages. We wanted to run them by team & community to see what are their views:

Scenario 1:
Consider the scenario that we are releasing package arm-x that has pessimistic dependency on package B. Example: spec.add_runtime_dependency 'B', "~>1.0.0". We are using features of package B but do not expose package B’s apis directly on our package arm-x’s apis. When someone wants to use package ``B with version 2.0.2 with our package `arm-x` in their projects, they’ll ask us to relax dependency. Now questions on our sides are

1. When we release new arm-x package with pessimistic dependency of 'B', "~>2.0.0". Is that a breaking change / patch for package arm-x?
2. What circumstance we should consider using dependency like 'B', "[>=1.0.0, <3.0.0]"? Is it encouraged or discouraged in the community?
3. If we are already using dependency like 'B', "[>=1.0.0, <3.0.0]", when & how should we approach to use pessimistic dependency for that package? [Related Issue Relax mime-types gem pinning #482]
4. When we want to use newer version of one of the dependency package (Assume for example: Faraday 2.0.0 instead of current "~>0.8"). What things we should consider in general?

Scenario 2:
Considering that json package has been shipped by the ruby platform itself, is that acceptable to remove explicit json dependency from the package itself and rely on shipped json version? [Related Issue #490]

[vishrutshah]

Per our offline discussion, here are the answers:
Scenario 1:

1. When we release new arm-x package with pessimistic dependency of 'B', "~>2.0.0". Is that a breaking change / patch for package arm-x?
   Ans: Considering you don't affect any public APIs exposed by package arm-x that is a patch for package arm-x
2. What circumstance we should consider using dependency like 'B', "[>=1.0.0, <3.0.0]"? Is it encouraged or discouraged in the community?
   Ans: Prefer pessimistic operators as long as you can. There may be circumstances in backward compatibility then we can make decision to keep those around. General recommendation is to upgrade as you go. Leverage service like gemnasium
3. If we are already using dependency like 'B', "[>=1.0.0, <3.0.0]", when & how should we approach to use pessimistic dependency for that package? [Related Issue Relax mime-types gem pinning #482]
   Ans: Same as previous one/
4. When we want to use newer version of one of the dependency package (Assume for example: Faraday 2.0.0 instead of current "~>0.8"). What things we should consider in general?
   Ans: Breaking changes from your API packages as well as understanding your breaking changes of dependency packages.

Scenario 2:
Considering that json package has been shipped by the ruby platform itself, is that acceptable to remove explicit json dependency from the package itself and rely on shipped json version? [Related Issue #490]
Ans: Considering json is shipped with platform keep dependencies minimal.

Feel free to jump in if you have more preferences and things to be considered.

Thanks

[veronicagg]

@vishrutshah Let's summarize the results in our Documentation. #551

[lamont-granquist]

Based on something like 5-6 years of working on another large ruby project -- http://github.com/chef/chef -- the answer to this question:

What circumstance we should consider using dependency like 'B', "[>=1.0.0, <3.0.0]"? Is it encouraged or discouraged in the community?

Is that you should absolutely use that format, if the statement that you are making is accurate. By jumping from ~> 1.0 to ~> 2.0 you create a hard 'fence' in your dependency resolution where everything in a Gemset needs to update to B >= 2.0 in order to consume the latest version of your package -- which means that you often create a stop-the-world-and-bump-all-the-gems problem often along with a lot of temporary pinning in Gemfiles to unreleased master versions of gems.

The question you have to ask though is "does this gem really work with B 1.x still?" and if that is false, then of course you can't make this statement. If its true, then you should publish the largest range possible to cause the least amount of trouble in dependency solving for gemsets, to allow support for the 2.x version to filter slowly through your ecosystem.

The question of what to do when you drop support for B 1.x and if that is a major version bump on the package specifying the dependency is another issue. If it doesn't change your public API then I would assert that it is not. But this can cause issues where as part of a whole Gemfile a user has constructed they need some other tooling which only supports B 1.x and now you've 'broken' them because you can't bundle both pieces of software together due to a diamond shaped dependency conflict. We went down this road with chef-client depending on rest-client and it became very silly. We would up actually removing the code which depended on rest-client completely, but had to carry forwards the rest-client 1.x dependency in our gemspec because external consumers were treating that as a "public API" of ours. After 2.x was released and other consumers updated to "~> 2.x" that broke them, but we couldn't bump from 1.x to 2.x without breaking other users. We finally took a major version bump and dropped the dep completely -- which broke the users who were dependent upon that, but we basically washed our hands of that and declared that they should either explicitly state their own rest-client dep or else port their code to chef's internal rest client. This mess is also why its better to try to support as wide of a possible of range of versions of dependent packages . TL;DR: SemVer has sharp edges and does not address this edge case well at all and there's no clear answer for every use case.

[sarangan12]

Moving this to backlog

[sarangan12]

Added a page to link this issue https://github.com/Azure/azure-sdk-for-ruby/wiki/Versioning-Information

Since there is no more action items, I am closing this issue