maintenance goals for savon

[pcai]

A couple thoughts I wanted to share on priorities for this project. My hope is that even if others disagree with the goals and tactics here, they at least understand the process by which I've arrived at them. Thoughts, additional information, offers of help, and divergent viewpoints are all welcome, and I intend to evolve this document in response.

0. UP TO DATE: get current with ruby ecosystem

It's hard to make forward progress if we don't have a working definition of what we need to support, and a binary definition of whether we're meeting those goals. So we're going to arbitrarily target the current supported versions of ruby, and test using the lowest-effort CI. This should help with security issues as well.

In the past few years we've migrated most of the rusting CI systems to github actions and removed some broken configs (like rubinius). With the GH actions matrix testing, we can now easily test against new releases of ruby, including head.

Going forward, we need to stay on top of API changes to peer dependencies and libraries like rack, etc, but we're starting to get to a good place here - right now, most savon libraries are green against ruby-head and the latest versions of their deps with no warnings, and I'd like to keep it that way.

1. IN PROGRESS: improve stability / debuggability

Many contributions break things because of the complex nature of SOAP and an aging test suite that doesn't cover the many many different uses and corner cases. I'd like to make this better through a combination of:

• getting more test cases into the suite - usually a matter of deriving missing cases from bug reports. It's mostly useless and futile to read the SOAP specification and try to derive tests from it, as the only real test is "does it work in real life?" An analogy I like to use is that it's mostly useless to try and implement email by reading and implementing rfc5322; unfortunately the only test that actually matters is "what does gmail do?"
• making it easier to create actionable issues with stacktraces, repros, and things like guides/examples on how to contribute a failing spec. once the groundwork is laid and issue creators see how easy it is to do + how much faster it resolves their problems, hopefully this becomes a bit self-reinforcing
• resisting the urge to get too fancy - like with multiple concurrent supported versions, major API changes that don't focus on maintainability, etc. Right now our de facto policy (not formalized anywhere) is that we don't have multiple releases at a time - this means no backports, and de-prioritizing any reports that don't include a repro on the latest releases

2. TODO: get and stay caught up on stale issues and contributions

It's hard to discuss or manage contributions when the test coverage is lacking, but once we are in a better spot i'd like to get to a point where the community can quickly decide if something needs to be sent back / closed for more info, instead of being stuck in limbo because we don't know enough to act on it but also don't have enough infrastructure to make a specific request to move things along.

We'll also need to do a one-time scrub to get through a few years of cobwebs

3. IN PROGRESS: proactively improve maintainability

One example of this is finishing the deprecation of HTTPI in favor of faraday, which will put us on more solid foundation and reduces the duplication of work that would otherwise go to both HTTPI and faraday.

Another way in which we made progress here was migrating https://www.savonrb.com/ to a static site so that we didn't need to worry about hosting as much.

We should look for opportunities like this to make sure that the impact of every volunteer and every contribution is maximized in the future, even if the (short term) instability this causes is in tension with goal # 1.

How you can help

I don't use savon in my daily work, so it'd be helpful to have more core contributors who can sanity test proposed changes / recent releases against real systems, and report actionable issues. Also, improved documentation on how to report bugs and suggest reproductions / failing specs are probably going to have the biggest impact going forward.

tl;dr: A lot of velocity right now is limited by caution - there's a lot of friction in getting contributions merged because its pretty painful to chase down regressions caused by changes! And at the same time, there are a lot of moving parts - and thus a lot of surface area for unexpected interactions. We can make progress on both these fronts to get us to a much better place

[pcai]

some tips to develop/debug that I picked up but thought were non-obvious:

to install dependencies and start a repl in the bundled environment:

bundle install
bundle exec irb

once in irb, to run/debug the local branch in a repl:

# add current gem directory to load path, then load the gem
$LOAD_PATH.unshift(File.expand_path('./lib', __dir__))
require 'savon'

# so we can see the request and response body
LOG_LEVEL = :debug

# might need to disable ssl verification for the request to succeed, if your dev env is missing cert chains
SSL_VERIFY_MODE = :none # savon 2x
SSL_VERIFY_MODE = OpenSSL::SSL::VERIFY_NONE # savon 3x

# sample repro steps
SERVER = 'https://lists.cam.ac.uk/sympa/wsdl'
ATTRIBUTES = { "xmlns:ns0" => "urn:sympasoap" }
client = Savon.client(wsdl: SERVER, env_namespace: 'soap-env', namespace_identifier: 'ns0', log: true, log_level: LOG_LEVEL, ssl_verify_mode: SSL_VERIFY_MODE) 
login_msg = { email: 'asdf', password: 'asdf' }
response = client.call(:login, message: login_msg, attributes: ATTRIBUTES)
# etc