Zero migration topic

[Charlotte-Holt]

The feature overview topic will briefly discuss zero migration, but it would be beneficial to have a concept topic on zero migration. It should cover what zero migration architecture means and why it's helpful to developers.

Reference links: https://developer.ibm.com/wasdev/docs/liberty-zero-migration-vision/ https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/cwlp_migration.html

About Liberty kind of section.

[dmuelle]

HI @lauracowen First draft is now up at https://draft-openlibertyio.mybluemix.net/docs/ref/general/#zero-migration-architecture.html

Who should SME review?

FWIW, all the sources were from commercial Liberty. I did my best to adapt but may have missed some nuances. Also- do we want any discussion of what zero migration means in the context of using Maven/Gradle builds? If that's even relevant here

[lauracowen]

I like it.

• "Your existing APIs and behaviors are supported in new product versions" (and elsewhere) - maybe try to avoid the word "supported" (but might be worth chatting with Alasdair about it first). Although we normally mean "it works as designed with", it can be read as "officially supported by IBM" which it isn't unless they pay for it. In practice, it is supported in that anyone can raise a bug on GitHub and get a fix, but it's not paid support in that sense. So if you can use a different term (like "work"? or "continue to work"?), it would be less open to ambiguity. See what you think and what Alasdair thinks.

For SME, I think start with @NottyCode

[dmuelle]

Thanks Laura- I see what you mean and can replace references to "support" if necessary. Interested to hear what @NottyCode thinks as this is good to know in general when discussing OL features and capabilities. Is there a better term to use than "support" in an open source context? Taking a cursory look around, I do see it used fairly regularly in open source docs.

[lauracowen]

It's not so much the open source context (I agree, it gets used a lot) but the relationship between IBM supporting use of OL and OL as an OSS project. I'm tempted to say it doesn't matter but @NottyCode might know specific scenarios in which it does?

[NottyCode]

There are 11 instances of the words "you can" there are 3 in section 1, 5 in section 2 and 3 in section 3. It happens often enough I noticed and felt it was repetitive.

I think the intro needs to talk about why people would care about zero migration rather than stating we have it. Some of this is style, but for an intro I'd probably try something more like this:

One of the major pain points for people consuming runtimes like Open Liberty is the need to use the latest release to ensure that there are no security vulnerabilities, or other bugs that could cause outages. Historically this is a difficult and painful experience because new releases also introduce API or behaviour changes introduced, often for new function that isn't critical for your application usage, but might be for others. For this reason Open Liberty as a core design principle has the concept of zero migration when moving up to newer releases. Zero migration allows you to move to the latest version of Open Liberty with minimal impact to your current application deployments and configuration.

Zero-migration means that you can use your existing, unmodified configuration and application files with an updated version of Open Liberty without unexpected changes in application behavior. Your existing APIs and behaviors are supported in new product versions, and new APIs and behaviors are added in new features and feature versions.

[NottyCode]

These sentences read as saying the exact same thing just 5 different ways:

Open Liberty never modifies user configuration files, which are fully compatible between versions. You can use a single version of your configuration files across multiple product versions. You can use files that you created for a previous version of Open Liberty with a later version. You can use files that you create for later versions with previous versions. As a result, if all configured features are installed, you can use a single set of configuration files across multiple versions without modifications.

[NottyCode]

I think the section titled "Pluggable Features" should probably be just "Features" reading elsewhere in the docs we don't call them "Pluggable Features", although they are described as being pluggable. It just makes it sound like the name is "Pluggable Features" where as the name is just "Features".

[NottyCode]

I would not say "migrate" here, I'd say "change". I would also not say "never need" because if it is possible that a security vulnerability might necessitate an application change, it doesn't happen often, but if leaving behaviour as is would be a major security issue we would fix the security issue even if it caused an application issue since it is better to be secure.

If you continue to use the same feature version, you never need to migrate your application.

[NottyCode]

For example, Open Liberty supports both the servlet 3.0 and 3.1 specifications.

No it doesn't, Open Liberty supports servlet 3.1 and 4.0, but not 3.0. This is prevalent in the section this is mentioned in.

[NottyCode]

...most commonly the Java SDK. Java EE 7 features, for example, require Java version 7 as a minimum. Therefore, adding a Java EE 7 feature to your server configuration might require you to use Java SDK 7 or later.

we don't support Java SDK 7. In any case it should be written Java SE 7. The minimum Java version is Java SE 8. In theory some features might prereq newer Java SE versions, but there are no current examples that I'm aware of.

[NottyCode]

Open Liberty recognizes several exceptions to the zero migration principle.

At this time Open Liberty has not developed the higher level cognitive awareness implied by this sentence. We the team behind Open Liberty does, but Open Liberty itself doesn't. Not sure of the best way to phrase this, but it would be good to rephrase.

[NottyCode]

Open Liberty does not control APIs from the third-party class loader configuration. As a result, updates to third-party components are not guaranteed to be compatible with an earlier version of the runtime.

We should probably state that this is why we do not expose 3rd party API's by default.

[NottyCode]

I don't really understand the intent of this:

In rare cases, Open Liberty must withdraw a feature or supported software product. In these cases, users receive removal notifications at least two years in advance. However, these notifications do not cover situations where other software suppliers remove support for their product earlier than Open Liberty does. Be aware of the the lifecycle dates of third-party products that you are using with your Open Liberty installation.

I'm not sure where it comes from, but it seems to conflate support for other software (which we don't document here) with removing features (which we have never done) and I don't understand the However. Do we know where this came from?

[NottyCode]

The Open Liberty code base is common with the WebSphere® Application Server traditional code base. Therefore, some configuration properties in the Open Liberty code base might not be documented, but when specified, might affect the behavior of Open Liberty. Because these configuration properties are not documented for Open Liberty, they are not supported. They were not tested for Open Liberty and might not work reliably now or in the future. Since these properties are not documented as a product external, they can be removed at any time.

This might make sense in the context of WebSphere Liberty, but since this is Open Liberty documentation I think it is confusing. I wouldn't say "not supported" here because of the confusion the term can introduce as @lauracowen says. Perhaps something like this:

There may be configuration options for Open Liberty that are not part of the runtime documentation, these configuration options may be determined by looking at the source code, or through trial and error based on external sources of information. If they are not documented as a part of Open Liberty then they are not considered part of the product externals, may not be fully implemented and may cause issues if used. Since these are not documented they may be removed or changed at any time and are not covered by zero migration.

[NottyCode]

Historically, new Java SE versions make few incompatible changes to the Java language. In the rare case that a breaking change is included in a new Java version, Open Liberty attempts to minimize the impact of these changes on applications.

I think the last sentence should really make it clear that Open Liberty may fail the attempt.

[NottyCode]

Zero-migration architecture saves developers and enterprises time and money by avoiding the need to migrate existing configuration and application files. Instead, developers can use new capabilities and features to write new applications while they continue to benefit from improved performance and administration for their existing server configurations.

The second sentence reads strangely to me. It doesn't seem related to zero migration because it is about using new stuff, not the old stuff. I suspect what is intended here is to say the developer can focus on delivering new stuff to their application rather than having to update their application to cope with runtime changes.

[dmuelle]

Thanks for reviewing @NottyCode - I've made edits to address each of your comments above.

https://draft-openlibertyio.mybluemix.net/docs/ref/general/#zero-migration-architecture.html

[dmuelle]

Hi @NottyCode circling back on this issue. I believe I've addressed all your comments in the updated draft. When you have a chance, can you let me know if this doc needs any further edits or is ready to publish from a technical perspective? If possible, can you let me know by Wednesday 6/17? Targeting this for OL and OL in RHR 20.0.0.7

[NottyCode]

@dmuelle sorry I didn't see the notification from GitHub about the update. Some comments.

User Configuration I don't think this needs to be stated:

Open Liberty never modifies user configuration files...

it is true, but it doesn't feed directly into zero migration

Also in User Configuration I don't know what relevance the 2nd paragraph has to zero migration:

Open Liberty provides an absolute separation between product files and user files. Product files do not need to be modified by users. By default, user files such as server configuration and application files are located under a separate directory from the product files. If you want to override the default location for user files, you can specify a new location by setting the WLP_USER_DIR environment variable. For more information, see Server configuration.

Features section

I am still unhappy with the term pluggable features, although I don't know what my suggestion would be. In any case I am struggling with the intro:

Open Liberty features are pluggable. Your existing features are supported in new product versions. You can add, remove, and update features as needed, with minimal impact on your application. Open Liberty uses pluggable features to support multiple versions of an API. Changes in API behavior are enabled in new feature versions so that you choose the appropriate feature version for your application. These versioned features continue to work across runtime updates.

I would probably express it more like this myself:

Open Liberty features are critical to how zero migration for application behaviours works. Which features of Liberty are used are encoded into the server configuration which is not changed during an upgrade. When behaviour changes need to be introduced, perhaps due to a specification mandating a behaviour change, this is introduced via a new version of the feature. Existing applications and their configuration have the old behaviour, even though new applications can choose to use newer feature versions to get the new behaviour.

Exceptions

I'm still uneasy about how this is introduced. Rather than this:

Several exceptions exist to the Open Liberty zero migration principle. Although these instances are rare, in the following scenarios you might need to modify your application or configuration:

How about something along these lines:

Although we endeavour to ensure no breaking changes there are some cases beyond our control where we may not be able to. These exceptions to zero migration are rare and fall into one of these categories:

[dmuelle]

Thanks @NottyCode. I've adopted your suggestions with some minor edits per IBM style. https://draft-openlibertyio.mybluemix.net/docs/ref/general/#zero-migration-architecture.html

Let me know if anything further is needed or if you're ready to approve. Thanks

[NottyCode]

Looks good to me

[lauracowen]

If Alasdair's happy with it, I'm good (for this topic).

[Rwalls1]

Peer review

The topic looks good, I just have a few comments:

• The sentence, "With zero migration, you can move to the latest version of Open Liberty with minimal impact to your current application deployments and configuration.”, feels a bit redundant due to a similar sentence being included. I think it could be removed as the second paragraph should probably focus on why that is important, which is already explained in the paragraph. 
• The phrase, “running version”, does not seem clear enough here to me. I think it could potentially be confusing. I think changing the phrase to something like “current” or “active” version would be more effective.
• I think you should avoid using the phrase “application business logic” without providing further context for what it means. Based on what I could find, there doesn’t appear to be a standard definition for what “business logic” is so it may be best to briefly explain what it means within the context of Open Liberty if you want to use the phrase.

[dmuelle]

Thanks for reviewing @Rwalls1 - addressed your comments in a new draft:

• The sentence, "With zero migration, you can move to the latest version of Open Liberty with minimal impact to your current application deployments and configuration.”, feels a bit redundant due to a similar sentence being included. I think it could be removed as the second paragraph should probably focus on why that is important, which is already explained in the paragraph. removed
• The phrase, “running version”, does not seem clear enough here to me. I think it could potentially be confusing. I think changing the phrase to something like “current” or “active” version would be more effective. edited to "active", since "current" might be confused with "most recent"
• I think you should avoid using the phrase “application business logic” changed it to "applications", since that captures the meaning more simply in this context

[dmuelle]

new URL: https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/zero-migration-architecture.html

[chirp1]

Hi David, Here are my updates:

• For "behaviors are added in new features and feature versions. ", you do farther down in the topic explain what a feature version is with an example, but if in this initial paragraph you could briefly explain what you mean b y a feature version, you could make more clear what a "feature versions" means and set the tone for the rest of the topic. Otherwise, a user could initially think that it is just an update to a feature, not infact a new numbered version of the feature.
• For "either for a fix pack or a new version. ", I don't believe that OL has fix packs.
• For "to use the old behavior", maybe add something like "and the old feature" to improve clarity.
• "Modify your application to work with the new feature version. " seems redundant with the sentence immediately preceding it.
• I think that for "The feature manager is configured by using the featureManager element in the server.xml file. Each feature that is required is configured by using the feature element. " the user is doing the configuring. If so, use active voice. Also, for "server.xml file" can the user also put features in include files? I think that the two sentences could be combined into one sentence.
• For "other features and are sensitive to the feature versions ", would the feature actually require a specific version of the other feature when you say "sensitive"? If so, rewrite the sentence. Also, for "both configured into the same server. ", use a different preposition than "into".
• "Some features require...." sounds like an example. If it is, indicate that it is an example.
• For "not considered part of the product externals ", since OL isn't a product, reword, likely changing "product" to "Open Liberty".

[dmuelle]

Thanks for reviewing @chirp1, I made the following changes based on your review:

• [x] For "behaviors are added in new features and feature versions. ", you could make more clear what a "feature versions" means and set the tone for the rest of the topic. Added a brief explanation in 2nd paragraph

• [x] For "either for a fix pack or a new version. ", I don't believe that OL has fix packs. removed

• [x] For "to use the old behavior", maybe add something like "and the old feature" to improve clarity. added

• [x] "Modify your application to work with the new feature version. " seems redundant with the sentence immediately preceding it. removed

• [ ] I think that for "The feature manager is configured by using the featureManager element in the server.xml file. Each feature that is required is configured by using the feature element. " the user is doing the configuring. If so, use active voice. Also, for "server.xml file" can the user also put features in include files? I think that the two sentences could be combined into one sentence. I don't see this content anywhere in this doc- were you looking at the feature overview page here?

• [x] For "other features and are sensitive to the feature versions ", would the feature actually require a specific version of the other feature when you say "sensitive"? If so, rewrite the sentence. Also, for "both configured into the same server. ", use a different preposition than "into". revised

• [x] "Some features require...." sounds like an example. If it is, indicate that it is an example. This sentence is not an example of the previous sentence, but a separate point. I made it clear that the reference to the JVM is an example- is that what you mean?

• [x] For "not considered part of the product externals ", since OL isn't a product, reword, likely changing "product" to "Open Liberty". changed to "Open Liberty"

[chirp1]

Hi David,

The updates look good, and the article looks nice! I do see that for "The feature manager is configured by using the featureManager element in the server.xml file...", I inadvertently commented on the Feature Overview topic. I'm moving the topic to the Ready to Publish column.

[dmuelle]

Doc is now on vNext branch, will publish with 20.0.0.12 on 11.20. Closing this issue