Release responsibly (Maintaining Backwards Compatibility)
0 likes•1,892 views
The document discusses best practices for maintaining backwards compatibility when releasing software updates. It recommends having a simple API, clear communication about what is supported, and following semantic versioning. Specific techniques are provided like adding new methods instead of changing existing ones, using deprecation strategies, and anticipating needed changes to ease future transitions. Communication is important to set expectations and build user trust. Compatibility must be balanced with innovation.
![def add_user(username, password=nil, read_only=false, opts={})
begin
user_info = command(:usersInfo => username)
# MongoDB >= 2.5.3 requires the use of commands to manage users.
# "Command not found" error didn't return an error code (59)
# before MongoDB 2.4.7 so we assume that a nil error code means
# the usersInfo command doesn't exist and we should fall back to
# the legacy add user code.
rescue OperationFailure => ex
raise ex unless COMMAND_NOT_FOUND_CODES.include?(ex.error_code)
return legacy_add_user(username, password, read_only, opts)
end
!
if user_info.key?('users') && !user_info['users'].empty?
create_or_update_user(:updateUser, username, password,
read_only, opts)
else
create_or_update_user(:createUser, username, password,
read_only, opts)
end
end
Ex: Gory details](https://image.slidesharecdn.com/releaseresponsibly-pdf-140912104229-phpapp01/85/Release-responsibly-Maintaining-Backwards-Compatibility-17-320.jpg)
![Ex: Insert operation
# lib/mongo/operation/write/insert.rb
...
!
def execute(context)
if context.write_command_enabled?
op = Command::Insert.new(spec)
Response.new(op.execute(context))
else
context.with_connection do |connection|
Response.new(connection.dispatch([ message,
gle ]))
end
end
end](https://image.slidesharecdn.com/releaseresponsibly-pdf-140912104229-phpapp01/85/Release-responsibly-Maintaining-Backwards-Compatibility-37-320.jpg)
Release responsibly (Maintaining Backwards Compatibility)
- 1. Release Responsibly (backwards compatibility) Emily Stolfo Ruby Engineer at @EmStolfo
- 2. The lifetime of our Gemfile.
- 3. source :rubygems ! # Generic gem “rake” if RUBY_VERSION < “1.9.3” gem “activesupport”, “~>3.0” else gem “activesupport” end ! # Deploy gem “redcarpet”, “2.2.0” ! # Testing gem “mocha”, “0.13.0”, :require => ”mocha/setup” gem “shoulda”, “3.3.2” gem “shoulda-matchers”, “~>1.0” gem “test-unit”, “2.5.0” ! # JRuby platforms :jruby do gem “jruby-jars”, “1.7.13” end
- 4. Innovation and Stability are in conflict in the Ruby community.
- 5. a gem version breaks backwards compatibility… “Not part of the official API” “My bad, sorry” yank the gem, release a new one
- 6. Release Responsibly (backwards compatibility)
- 7. “What’s the deal with the Ruby driver? ! Do newer versions of the driver support all older versions of the server?”
- 8. “Not quite…”
- 9. Your code will be backwards compatible if you stick to 3 things.
- 10. SIMPLE API CLEAR COMMUNICATION SEMANTIC VERSIONING
- 11. SIMPLE API
- 12. Configurability and Stability are at odds.
- 13. www.gov.uk
- 14. Some ways to safely make API changes.
- 15. DO • Add arguments with default values, so old method calls still work. • Add methods. • Add subclasses. ! DON’T • Add arguments without default values. • Rename methods or classes. • Remove arguments from method signatures.
- 16. Modularize (hide all the gory details)
- 17. def add_user(username, password=nil, read_only=false, opts={}) begin user_info = command(:usersInfo => username) # MongoDB >= 2.5.3 requires the use of commands to manage users. # "Command not found" error didn't return an error code (59) # before MongoDB 2.4.7 so we assume that a nil error code means # the usersInfo command doesn't exist and we should fall back to # the legacy add user code. rescue OperationFailure => ex raise ex unless COMMAND_NOT_FOUND_CODES.include?(ex.error_code) return legacy_add_user(username, password, read_only, opts) end ! if user_info.key?('users') && !user_info['users'].empty? create_or_update_user(:updateUser, username, password, read_only, opts) else create_or_update_user(:createUser, username, password, read_only, opts) end end Ex: Gory details
- 18. Have a Compatibility module.
- 19. Use Polymorphism instead of conditionals.
- 20. Backport only when necessary.
- 21. Ex: OrderedHash module BSON class OrderedHash < Hash ! def ==(other) begin case other when BSON::OrderedHash keys == other.keys && values == other.values else super end rescue false end end ... end end
- 23. Compatible with what? ! 1. Your older API 2. Older system(s) you integrate with
- 24. Define the scope of what you support.
- 25. Ex: Ruby driver
- 26. Test everything you say you support.
- 30. User trust should be a priority.
- 31. “Not part of the official API” “My bad, sorry” yank the gem, release a new one
- 32. Ex: Gem released breaking 1.8.7 support Q: Maybe you can change the gemspec to official say you don’t support 1.8.7? A: We don’t use the gemspec because we only support alive Ruby versions.
- 33. Have a deprecation strategy.
- 35. Ex: strict mode # lib/mongo/db.rb ... ! # @deprecated Support for strict will be removed in version 2.0 of the driver. def strict=(value) warn "Support for strict mode has been “ + “deprecated and will be removed “ + “in version 2.0 of the driver." @strict = value end
- 36. Anticipate deprecations when designing.
- 37. Ex: Insert operation # lib/mongo/operation/write/insert.rb ... ! def execute(context) if context.write_command_enabled? op = Command::Insert.new(spec) Response.new(op.execute(context)) else context.with_connection do |connection| Response.new(connection.dispatch([ message, gle ])) end end end
- 38. Ex: Insert operation # lib/mongo/operation/write/insert.rb ... ! def execute(context) op = Command::Insert.new(spec) Response.new(op.execute(context)) end
- 40. Why don’t people follow SemVer?
- 41. SemVer is a double-edged sword. ! - a Bundler maintainer
- 42. Gemfiles could be cleaner.
- 43. source :rubygems ! # Generic gem “rake” if RUBY_VERSION < “1.9.3” gem “activesupport”, “~>3.0” else gem “activesupport” end ! # Deploy gem “redcarpet”, “2.2.0” ! # Testing gem “mocha”, “0.13.0”, :require => ”mocha/setup” gem “shoulda”, “3.3.2” gem “shoulda-matchers”, “~>1.0” gem “test-unit”, “2.5.0” ! # JRuby platforms :jruby do gem “jruby-jars”, “1.7.13” end
- 44. It’s a culture/ community thing.
- 45. end