Are config-schema changes breaking?

[josephjclark]

This issue is to discuss whether a change to the configuration schema of an adaptor should result in a major release bump.

Because I still don't know and I think we should have a clear policy for this going forward.

Arguments for:

• A job written for one version may break in another version. I mean it is a breaking change.

Arguments against:

• You're only breaking the credential, not the job. It's not a breaking change.
• Job code is actually unaffected
• It's annoying to bump the major for what is often a trivial change

Perhaps this debate could be mitigated by some means in Lightning to a) bind a credential to an adaptor version, and b) detect conflicts should the adaptor version change.

[taylordowns2000]

I'd argue that not all config changes are breaking changes. Some are clearly patches (e.g., removing that hostname validation thing from a handful of adaptors.)

Could we say that:

1. if we do introduce a breaking change to how config is handled (we drop support for state.configuration.apiUrl and only support state.configuration.api2rl or something) then it is, of course, a breaking change (MAJOR); but
2. if we are merely fixing or enhancing the configuration schema so that Lightning can more faithfully produce JSON blobs which work as state.configuration for a given adaptor version, then these are patches (PATCH) (e.g., the hostname validation stuff) or new features (MINOR) (e.g., adding apiVersion to an adaptor that previously didn't take an API version.)

--

Separately, I think we need Lightning to provide credential building/editing templates for specific adaptor versions, not just for adaptors. But that's different, right?

[josephjclark]

@taylordowns2000 I think that makes sense, but we may find it introduces a lot of breaking changes. Relaxing rules isn't breaking, but anything makes them more specific is.

What I'd really like is to be able to say "treat all schema changes as patches". I just don't think I can justify it - switching the adaptor version WILL break the workflow, so strictly speaking it should be treated as a major.

I guess I just need to live with it huh.

Agree with you the Lightning thing, but that's a different story :)

[taylordowns2000]

So far there haven't been many, and I'd argue we should be totally cool with language-salesforce-v37 😎 .

I'm 100% with you on what is/isn't breaking and I'm still arguing for a strict SEMVER interpretation.

1. Sometimes we relax validation or fix bugs, this is PATCH.
2. Sometimes we add new optional fields to adaptor config, this is MINOR.
3. Sometimes we add new required fields or change how existing fields behave, this is MAJOR.

If we wanted to flip this around and say, "all configuration-schema changes are patch" I'd actually be totally OK with that, so long as you analyzed the adaptor code itself with strict SEMVER adherence. How it would play out if we adopted that approach:

Story A

• You make a change to the config schema (add your PATCH to the changeset; config-schema is always a patch)
• You don't make a change to the /src since there's zero change to be made. (maybe you were relaxing validation or changing a label for a form geneator? who knows.)
• This gets released as a PATCH.

Story B

• You make a change to the config schema (add your PATCH to the changeset; config-schema is always a patch)
• You do make a change to the /src (maybe this is MAJOR, maybe it's MINOR, maybe it's PATCH)
• This gets released as whatever the change to /src was. Don't worry about the config-schema, that's a helper for an external tool. The important thing is that if you've introduced a breaking change to how state.configuration.blah gets treated, we've got our major bump.

I'm happy in both the "a" and "b" stories. Does this better reflect the ethos of the "config changes are just patches" while still maintaining SEMVER for our users?