In general Z customers don't expect APIs to break their code but rather for changes to not break clients but they could introduce new function. I know its not open source or agile but no one wants the code they write to break a year later ...

What kind of breakage are we talking about ? Sample ? Is there a conversation in Slack with examples ?

The sample breakage brought up in discussion was the CLI changing a parameter name - e.g. from "--password" to "--pass" (the example was not this specific field, I can't remember which one was brought up). This would break any scripted environments using the CLI in a CI/CD pipeline.

Ideally in most cases we should modify APIs by extending them, and we should version API interfaces to protect clients from breakage (e.g. REST APIs /v1/functionA vs /v2/functionA ). The goal of this discussion is to have a plan for when we cannot adhere to those guidelines and must break some API - how does the larger Zowe deliverable handle it in terms of versioning/release & transparency/documentation.

CLI already has aliases for quite a few parms, e.g. "data-sets" can be shortened to "ds' or "local-files" to "ls" and both arguments work. Would it be possible to provide support for both the long and the short version of password ? I agree with @hogstrom and others that we should do all we can to not introduce API breaking changes mid version as a precedent

In this instance, I would continue to support both and put out a deprecation warning. Something like:

The usage of command line parameter --password is being deprecated and will be removed in 2.0. Please use --pass instead.

The consequence is that doing that would require the enduser to modify every one of their scripts prior to 2.0. A lot of busy work that doesn't make their life any easier and adds to their todo list. Worst case, causes service disruptions because people ignored the message. In the end, diminishes the value of project making minor changes like that.

Assuming that we take an N-2 approach on API deprecation (for instance, in this case assuming it is --password in 1.0 and would no longer work in 4.0 but would be tolerated in 2.0 and 3.0) I think the negative impression could be avoided.

For those in the Z world, they still run code that was written 30 years ago with no required updates and its a platform value proposition.

Net, I'd say inform of deprecation and support N-2 as a best practice.

I agree with this approach. Can we request the squad leads review this and confirm their API status and intended compliance with deprecation / N-2 approach?

Needs a formal proposal for development guidance for projects to sync on for support.

Sean's input is to use time instead of versions to decouple from community release velocity.

@armstro @MarkAckert

@armstro bruce to propose a document with the plan. Review next week

Proposal is for squad leads and ZLC to identify a release within the last 2 weeks of 3Q of each year worthy of being designated a Long Term Support Release (LTSR). The release would be declared a LTSR candidate for 30 days and request consumers of the release to do any additional testing of the LTSR candidate. After the 30 day candidate period and with input from the squad leads and any other contributors, the ZLC will vote to designate the release a LTSR. (Note: The LTSR may or may not be on a version boundary. The LTSR can be the last release of a version or a release within a version.)

Once designated a LTSR, the source code tree (and convenience build and the build process) would be supported by the open community for a period of 2 years from the date of the LTSR approval vote. The source code and executable would be updated for only fixes during the 2 year period at the discretion of the committers. The intent of the LTSR is to allow consumers of the code a 2 year stable window of time for use in customer environment and therefore not to be frequently updated. Fixes would only be provided for defects impacting a production environment with no viable work around or in the event of a security exposure identified after the 30 day testing period of the LTSR candidate.

The source code tree of a LTSR is to remain on the OMP Zowe site indefinitely for use by anyone with committer status. (The build scripts used at the time would also be provided but not guarantee of a build environment after the 2 year LTSR support period).

Example node.js support https://nodejs.org/en/about/releases/

@jlvignaudCA @jplinardon sorry if you see this twice - I want to confirm you see my proposal for you to have time to consider it before ZLC tomorrow - net of the proposal is a LTSR designated once a year to be supported by the open community for 2 years. Source code available for 5 years for anyone to use as they see fit (i.e., like a fee based support offering) BUT no guarantee of a build environment after the 2 year support window.

Question for @MarkAckert and @jackjia-ibm on the feasibility of supporting yearly LTSR and the build process for 2 years.

@alvin-tan @Tbr00ksy FYI

I think the fundamentals are good. Are there any consideration or explicit guarantees in regards to migration between LTSR versions?

@jplinardon To me (open to debate) the migration effort is between versions of Zowe and not necessarily related to LTSR. Release to release "should" have backward compatibility. Moving to a new version might have migration considerations. (Even moving between versions we need to minimize any migration pain but a new version will be a boundary that allows properly documented "breaking changes".) I think the last release of a version will generally be a LTSR. But I think there can be a LTSR that is not a different version with migration considerations.

There will come a time when we need to move from V1 to V2. Part of the reason I say the LTSR candidate is decided by squad leads and ZLC is to help decide when to make a LTSR and the specific verionsing/numbering scheme not be set in stone. I propose the last release of version 1 be the LTSR before we shift to a V2. So it might be V1.10.x (or whatever the middle digit is at the time of the decision). Since we have some anticipated "breaking changes" (i.e., NPM naming impacting CLI install scripts) on the horizon that cause us to move to a V2. We will need to get a V1 out the door for consumers to begin using and can depend on. After V1, maybe there is not a need for a V3 on exactly a year boundary from V2 (with breaking changes). We could go some period of time with V2.10.x as LTSR in 2020 and V2.20.x in 2021.

The impact to the version of Zowe is the community would have a LTSR source code tree at the V2.10.x level for any fixes and another LTSR source code tree some period of time later for V2.20.x.

Related topic to be discuss is what criteria do we want to establish to define when V1 is a LTSR. I recommend the SMP/E work needs to get done along with "new install and config" (aka the CUPIDS work) as well as better Logging and Messaging, Diagnostics. I've received feedback getting all this done in time for my proposed 3Q declaration of V1 LTSR is too ambitious but I think we make it as a goal and assess closer to time.

Zowe Support - LTSR Discussion .pptx
Slides for Zowe face to face for discussion on LTSR and related topics

Currently conformance is "self certification". I would like us to move away from this towards test compatability kit or TCK, which is where we have automation tests that a conformance product can run which tests whether an offering is compliant with the API/touchpoints of A desktop plugin or A CLI plugin or An API ML southbound server or A user of the base APIs or A user or the base CLI commands or an extender installing on top of Zowe adding plugins, southbound servers. The TCK protects the extender and also the TCK protects the Zowe squad from borking offerings that run on top of them

Zowe LTSR Proposal for ZLC 0814a.pdf

as discussed at ZLC today

note: this is an example of what an LTSR could look like, not a final proposal

It's a trivial matter - but why LTSR instead of LTS? I hadn't come across LTSR and had to google it.

In Ubutu, Eclipse, Node.js, and many others I see LTS instead of LTSR. Should this be changed to be more familiar? 😄

Blame it on IBM-speak - https://www.ibm.com/support/pages/ibm-software-support-continuous-delivery-lifecycle-policy - I have no problem using LTS - well other than just need to train my brain to use it...LTSR just rolls off the tongue easier (for me). LTS going forward to be "open".

LTS sounds more familiar to me. MQ team apparently likes the LTS route too 😉 .

LTS sounds good to me, this way I can stop repeating myself when I say LTSR Release

Based on Oct 9 ZLC meeting discussion on LTS, I propose the following as a stated support policy for V1.x of Zowe and introduction/preview of Zowe 2.0. This is a DRAFT ONLY - we need to edit and agreement by the ZLC and squad leads:

_The Zowe community intends to issue a release in 1Q2020 that will be serviceable via the vendor-neutral SMP/E install and PTF process currently previewed on zowe.org. (Insert link to Alpha.) In addition to SMP/E, the Zowe code is being restructured into binaries, configuration and instance data (aka CUPIDS) to provide more flexibility in the set up, execution and maintenance of Zowe. This 1Q2020 release will begin a new phase of the Continuous Delivery (CD) support model for Zowe. Consumers of Zowe will be urged to move to this upcoming release. Fixes and enhancements will be delivered in future releases of Zowe using the SMP/E PTF process. The pax file format will continue as an equally supported install option for quick and easy installs but without the benefits of SMP/E controls.

It is the Zowe community intent to deliver a Long Term Support (LTS) release in 2020 once a set of enhancements are made in Zowe V1. The planned enhancements are viewable via Zenhub in the Zowe community located here. (Insert link and pointer to Zenhub plug in.) The Zowe community intends to make Zowe 1.x a LTS once the issues tag as "LTSR" are shipped in Zowe V1.x. The LTS release will be supported by the open community for 2 years from the date of availability. LTS updates will fixes only - no new enhancements are planned.

At the time of the Zowe 1.x LTS release, Zowe 2.0 will become the active development release. Future enhancements will be delivered in 2.x. Any code changes in Zowe V2 that impact backward compatibility with 1.x will be clearly documented 1 year prior to end of support of 1.x for consumers of Zowe for their planning and migration purposes. _

What - if anything - to say about "switch"? (In seeking advice from dev/test teams in IBM, the use of config switches is an extra burden on testing with many more permutations and combinations due to switch settings - we need to discuss how we want to handle.)

Optional paragraph: ?????
Subsequent releases after this 1Q2020 deliverable will - as best as possible - will have a configurable file setting to control whether new enhancements are enabled or not. The purpose of this "switch" to allow consumers of Zowe a degree of control over the enhancements in the execution of Zowe. Future enhancements will be delivered in 2.x included enabling - by default - the various 1.0 enhancements controlled by the configuration switch.

Another suggestion is Zowe how, when, if to provide a "deprecation warning message".....i.e. "use of parm "password" will be deprecated in V2".........

General comment is above policy needs additional work - plan is to adopt more node.js terminology and to provide visualization of the support plans.

I iterated on Alvin/Bruce's release proposal: Zowe OSS 2019-20 Roadmap.pptx

Some details:

1. I would say 1.x has already been operating in "current" mode.
2. We started "Active LTS" when we said we will no longer introduce breaking changes into Zowe 1.x. I don't think we need to align SMP/e drop with "Active LTS" if we've already stopped introducing breaking changes into 1.x.
3. We should always start the "next" release of Zowe when the "current" one moves into "Active LTS" status. This is needed as the devs will need some release to put breaking changes in and ISVs can validate compatibility/prep for conformance using the "current" release.

@solsu01 Thanks for making another iteration on the LTS design.

For Zowe V1, I agree we are not making breaking changes so may be past the "current" phase but we need the SMP/E work to claim "Active LTS".

The SMP/E work is first step to doing what the team calls CUPIDS. This is needed before we can enter into Active LTS on z/OS. Today's Zowe z/OS install and config is not modular (my term). CUPIDS is addressing that requirement. CUPIDS = Componentized Update Package Install Distribute and Service. I think CLI is a "replace all" install process and has one instance on a laptop/desktop. The z/OS components need to allow delta changes (not full reinstall), modular startup, config files separated from runtime and the option of running multiple instances if needed.

Ok, it might be better to just leave it as "Current" until SMP/e first drop then.

Updated: Zowe OSS 2019-20 Roadmap.pptx

I agree with Bruce's comment on SMP/e. Without SMP/e, providing incremental maintenance is technically feasible but highly error prone and painful, requiring binary-by-binary replacements. Matt has previously described the current install method as a "breaking change" because every release requires clobbering the old one, or keeping the releases separate without native migration tooling.

We should always start the "next" release of Zowe when the "current" one moves into "Active LTS" status. This is needed as the devs will need some release to put breaking changes in and ISVs can validate compatibility/prep for conformance using the "current" release.

I don't think this should be required, but Zowe's "next" release timeline should start sometime before the prior "Active LTS" ends. Do we have a proposal for our Active LTS and Maintenance LTS windows? 1 year each - so 2 years total support from the day we declare "Active LTS"?

@MarkAckert

Do we have a proposal for our Active LTS and Maintenance LTS windows? 1 year each - so 2 years total support from the day we declare "Active LTS"?

In my revision to Alvin's proposal (Slide 2 on Zowe OSS 2019-20 Roadmap.pptx), I am proposing 1 year of Active LTS followed by 1 year of Maintenance LTS which adds up to 2 years of total support from the day we declare Active LTS.

I think it would be good to have every release in LTS (combination of active and maintenance modes) for 2 years. This seems to be the sweet spot in the mainframe world since z/OS releases are once every 2 years now. People stagger their other software upgrades on z/OS on the same 2 year cycle.

Zowe.OSS.2019-20.Roadmap Rev 1.pptx

OK - thanks for the comments. See Rev 1 of deck - removed slide 1, created new slide 2. Slide 3 comes from the node.js site https://nodejs.org/en/about/releases/

1. We said we liked the Node.js description of current, active and maintenance so I have made an attempt to draw chart and create bullets along their policy. We can discuss in ZLC tomorrow (I hope).
2. Quick summary - I say we are in "current" now but it will not be the norm to have such a long "current" ....Node.js says "current" will be 6 months - we can debate if that is right for Zowe.
3. I find predicting when we declare Current to Active and Active to Maintenance hard to predict - node appears to give a month of year - do we have to say quarter? The chart I created is 1H or 2H of a year.

Related topics from comments above

1. Do we have the CLI go ahead and make breaking changes in V1 "current"?
2. Do we allow the squads to follow through on completing the items marked LTSR at their own pace (don't set a date) or do we set a date (mid 2020?) and discuss MVP to declare Maintenance LTS?

Thanks for iterating on the proposal @armstro .

I say we are in "current" now but it will not be the norm to have such a long "current" ....Node.js says "current" will be 6 months

I chalk it up to the longer "current" phase due to this being a new v1.x project.

With respect to the iteration on the proposal, I see a few differences of note in the new slide 2:

1. The length of LTS of v1.0 was extended to 1H2022 rather than ending at 1H2021.
   ^ I agree that LTS releases should generally be 2 years in length of LTS (Active + Maintenance), but v1.x usually carries a negative connotation with it in terms of stability. It's viewed as the first attempt which might not be quite production ready. If we think this perception is true, do we want to extend the length of 1.x or sunset it a bit faster so we can focus our efforts on 2.x which may not carry similar perception baggage?

2. v1.x and v2.x are overlapping in Active LTS and Maintenance LTS
   ^ I'm not sure I understand the purpose of 2 majors releases with mostly overlapping Active/Maint LTS where v2.x is in maintenance LTS for only 6 months longer than 1.x.

The draft looks great!!

My only comment is that there are dates "Feb 8th" mentioned in the charts. Is this ok? Are we ready to commit to that date?

Zowe.OSS.2019-20.Roadmap Rev 7.pptx
Modified chart and added bullet regarding backward compatibility

I think this draft gives us the necessary flexibility to commit and move forward. I propose we move to vote on this before year end.

What do we say about Conformance v1 (or Conformance 2019) users? Will they continue to work against Zowe v1.x Active LTS?

We discussed last week on the ZLC about breaking changes into the v1.x LTS drop....and this impacts for Conformance v1. If we intend to break, we must give the 60-90 day heads up if I recall correctly...

Attempt to make another rev of the slides for ZLC meeting 1/15/20 .....
Zowe.OSS.2019-20.Roadmap.Rev.8.pptx

Another attempt to state support and N-1 compatibility policy.
Zowe.OSS.2019-20.Roadmap.Rev.9.pptx

Also re-
LTS_Zoweorg_Design.pdf
attaching prior design for posting to zowe.org -

Zowe.OSS.2019-20.Roadmap.Rev.10.pptx

Two things:

• Let's translate this from a PPT and add to the release process docs. Needs to be done anyway - so might as well have the review done in that format to avoid the "lost in translation" issues that can happen.
• I don't see why we'd have the entire chart on the release process on the main page of zowe.org - I'd just reference the aforementioned Release Process docs and make things easier.

@armstro Definitely good to document - glad to see the collaboration here.

Looking at the node.js example, it is on a sub-page - which was sorta my point.

There is a larger picture of trying to consolidate docs - but that's a whole other conversation ;-)

Does conformance then tie to a specific Version and Release? Seems like a Version is not good enough if a breaking change can be introduced in a release update. I'm a little confused about how breaking changes fit into this model?

Sorry Matt - just saw this @hogstrom Conformance is tied to a version .....I find the term "breaking change" confusing - how about we clarify what that means - my proposal is

• Breaking change (with no work around)is on a version boundary
• Breaking change (or what I call "changes of note" like ++Hold jargon in SMP/E speak) that DO have a work around (via doc or config file change) are allowed on release boundary provided:
  Notice is given to the consumer ahead of time (doc, warning message, etc.). 
  Coordination with Conformance Criteria - conformance will be on version boundary 

For more on breaking changes, please see some discussion here: #152

Zowe.OSS.2019-20.Roadmap.Rev.11.pptx

Zowe.OSS.2019-20.Roadmap.Rev.12.pptx

Tks @armstro - I've added a new chart 2 to describe version, release, modification numbering (that I promised 2 ZLCs ago so apologies it's late) and I've also done some minor updates to try and describe the relationship with conformance program.

One question I have is that currently we provide a software distribution every 4-6 weeks v1 which will become active-LTS. When we begin v2 which will kick of Current, I imagine we will be building every 4-6 weeks also as we'll just switch active development to current. How frequently will we release active-LTS while current is in its 6-9 month period ? Would we also release active-LTS on the same frequency as current for 6 months, and if so when would we reduce the number of distributions when the switch occurs so current becomes active and active becomes maintenance ? Would we reduce those to be quarterly ? I'm wondering if on chart 1 we should discuss when software is released from each stream, or if not whether we should call out release cadence in the roadmap ?

Zowe.OSS.2019-20.Roadmap.Rev.13.pptx

Updated to include updates from Peter Fandel

Propose zowe.org site changes be done as follows
Zowe.OSS.2019-20.Roadmap.Rev.14.pptx
Support policy in words .docx

Recommend the New Conformance Program description and new process for Q&A be updated at the same time.....

@armstro @jmertic Hi Bruce, John,
For the LTS updates to be made on zowe.org, I previously created a PR and then closed. Based on the comment above, it seems the new design is as follows. @jmertic I can make these changes and open a PR for review if you prefer. Just let me know. Thanks!

• Create a Releases tab on zowe.org, right after the Download tab.
  • In the new Releases section, add the screen capture of the LTS roadmap and the bullet points that explains the roadmap briefly.
  • Add a button that links to detailed information in https://github.com/zowe/zlc/blob/master/process/ReleaseProcess.md.
• Add detailed and complete LTS information (the deck and the word doc information) into the Release process document in GitHub: https://github.com/zowe/zlc/blob/master/process/ReleaseProcess.md. Suggest we add a Table of Contents for easier navigation. Suggest add the information after What is a Zowe Release.

YES thanks @nannanli for being so attentive to this item. One minor change to the words in the Word Doc is to NOT link to the new conformance criteria (yet). @RASakach wants to rollout the new conformance criteria over time and the new plan to help people with Q&A. So my proposal is to just post the LTS info on zowe.org .......it would be great if you or @jmertic could do pull request and I would like to prev to the ZLC the new info before we go live. Thanks

@armstro Two PRs have been created for preview.

• Zowe.org update: Add Zowe LTS information to zowe.org zowe.github.io#75
• Release process document update to add the support policy: Add Zowe Support Policy #164

Zowe.org Preview screen capture

Providing update chart reflecting the actual date of 1.9 and stating 1.9 as LTS - I will propose this chart be used with the LTS policy description on zowe.org.
Zowe.OSS.2019-20.Roadmap.Rev.15 chart with dates .pptx

@armstro FYI - The chart screen capture has been updated in the PR. zowe/zowe.github.io#75

A few comments:

1. I would not call this "support policy". It would be better to call it something like "Release Timeline". People are confused about the term "Support" as they're mixing it up with enterprise support where they can call someone and receive support for using Zowe.

2. I don't think this line is necessary as it's misleading. The chart is self-explanatory and shows more than just LTS, it's the full release phases/cadence where LTS is only part of it.

Thank you @solsu01 ! Comments are incorporated. After revision:

Who has ppt? can it be reattached here please - Per ZLC discussion today (March 11, 2020) we want to adjust slightly to show new conformance roll out.