Backward compatibility policy

[armstro]

Using this issue to allow public discussion on Backward Compatibility Policy - this is to be a "companion policy" to the LTS issue. #72

Proposal is to post both at the same time.

Zowe LTS Backwards Compatibility.docx

[armstro]

Posting comments from email exchange:

1. what defines public vs non-public APIs? anything we published to the API catalog today out of the box? if this is what we have in mind, there's probably work to be done here since I don't think we document existing APIs in our Zowe docs today nor do we have Swagger docs for all APIs OOTB

We should do a full review APIs, but my starting point would be all APIs which are consumed by both "extenders" (building plugins) as well as "plain old users" (say, using out-of-the-box USS APIs or CLI commands). This type of categorization would include CLI commands but exclude ZSS APIs - ZSS APIs are consumed just within Zowe itself to my knowledge.

2. what options do we have wrt governance? How do we ensure we stay true to our commitments wrt non-breaking API changes? e.g. require automated test cases for all public APIs?

Test suites against APIs would be the gold standard and part of acceptance criteria for new code. When APIs go end-of-life, remove the test cases. Until then - incremental test coverage, code review, and planning/communicating...any other ideas for the short-term are welcome...

3. any particular reason why we decided to propose n-1 as opposed to n-2? (not saying it has to be n-2 necessarily, just want to hear your rationale)

Two main reasons:
'n-1' is the minimal compatibility guarantee we can give and is probably a good starting point. I'm cautious about statements which in practice would extend 3-5 years from now.

I feel like we're trying to toe a line between framework stability and evolvability. I have some concerns, potentially unfounded, that extended 'n-2' or 'n-3' compatibility guarantees would limit our capacity to evolve or remediate flaws in design that appear after extended adoption/growth. I also get the feeling that developers don't want to be locked into supporting decisions and APIs made, say, 4 years ago if we declare 'n-2' support. I may be wrong, and/or we need to become comfortable with that kind of approach.

4. wrt the Conformance program, personally I struggle with how its set up today. IMO, any certification program should be designed around major version boundary (1st digit) and not by year, it is the version (V1 vs V2 vs V3 ...) that uniquely defines the characteristics of a given release of project. Thoughts?

Agreed, I think our LTS and 'n-1' statements can lead the direction for the conformance program + conformance versions. Conformance can evolve within a major release (say Active LTS) to leverage new features or functions, and we should think about how to version and communicate that - but I like generally tying conformance to major releases at Active LTS+ stage. Current development stage - YMMV and nothing is promised (except n-1 backwards compatibility? )

[armstro]

For completeness - in email exchange positive comment to the "alternate proposal"

I like the alternate proposal. It gives us an opportunity to learn without making a public commitment. The squads should work as if n-1 was already the rule during this time. It should be in their working agreement/manifesto.

[Joe-Winchester]

@armstro - Does n-1 mean that an extender who has created a Zowe v2 conformant plugin can expect it to work with Zowe v1 ? That goes against what the conformance version boundary is for, which is to allow the product to introduce a new conformance program. Or does it mean that a Zowe v1 extension can work with Zowe v2, which again goes against the reasons for having a new version.
My understanding with n-x boundaries is related to a client connecting to a server, where the server can accommodate clients from two versions ago to avoid new client pushes having to be made.
I have a view of conformance which is that you get conformance for a version, and there is no guarantee that will work with a later version (or earlier) and you need to re-apply for and possibly code for new conformance

[armstro]

ZLC today felt this has been addressed based on description of Current, Active LTS - closing as complete.