"How to use Open Liberty betas" page

[yeekangc]

Create a page that provides instruction on how to use Open Liberty betas including configuring the beta features that one would like to check out.

Per @dmuelle, this can be an addition to the Basics section of Open Liberty docs.

Can be linked to from https://openliberty.io/downloads/#runtime_betas too. Actual instructions may be liked what is here: https://github.com/OpenLiberty/blogs/compare/betainstallsteps.

[yeekangc]

Cc @scottkurz @Joseph-Cass @GraceJansen @mbroz2

[dmuelle]

hi @yeekangc- this link doesn't show any info:

https://github.com/OpenLiberty/blogs/compare/betainstallsteps

is there another link for the beta install steps?

[dmuelle]

Or should this doc simply adapt the steps that are currently in the beta blog posts for All Beta Features/Jakarta EE 9 Beta Features "Try it now" sections?

[scottkurz]

@dmuelle I would say yes, take the steps like in this most recent post: https://openliberty.io/blog/2021/03/22/ldap-kerberos-21004beta.html and adapt those.

Three minor notes on those three steps.

• Step 1. "Add the following dependency to your pom.xml file:" - is unnecessary
• For step 3. I would add: " to the configuration section _ of the liberty-maven-plugin in_ your pom.xml file:
• Also in step 3., "Add add" => "Add"

I can open a separate issue if it helps? Not sure where the source lives for that template

[dmuelle]

Thanks @scottkurz

The template for that post is in the blogs repo: https://github.com/OpenLiberty/blogs/blob/prod/templates/beta-release-post.adoc

I can make sure whatever updates we make for this issue are replicated there. It's also possible that the template could be updated to just point to this topic.

For Step 1- just so I understand- you don't need to add that dependency to your pom? Is that because step 3. takes care of it?

[scottkurz]

For Step 1- just so I understand- you don't need to add that dependency to your pom? Is that because step 3. takes care of it?

Yeah, you could say that. The thought in documenting it as a dependency was that a dependency is a useful, common way to show a Maven artifact with coordinates. But operationally or instrumentally, it's a bit misleading since copying and pasting that dependency into your pom.xml, as a dependency, doesn't really accomplish what you're trying to achieve here (install this version/artifact for your target runtime).

[dmuelle]

Does that also apply to the Jakrta EE 9 Beta Features package? There's no runtime artifact listed for that one, just the dependency:

If you’re using Maven, here are the coordinates:

<dependency>
    <groupId>io.openliberty.beta</groupId>
    <artifactId>openliberty-jakartaee9</artifactId>
    <version>21.0.0.4-beta</version>
    <type>zip</type>
</dependency>

And then For step 2-

"Add a dependency for the beta version of each of the APIs that you’d like to try"

How does a user find the dependency details for the API? Should they look at "API packages provided by this feature" inb the feature documentation for the feature they want to enable?

[scottkurz]

Does that also apply to the Jakrta EE 9 Beta Features package? There's no runtime artifact listed for that one, just the dependency:

Yes it applies there. It does say in "Try It Now" in article: https://openliberty.io/blog/2021/01/26/ee9-messaging-security-21002-beta.html#jakarta to add to your plugin config (I'd still suggest my slight rewording).

How does a user find the dependency details for the API? Should they look at "API packages provided by this feature" inb the feature documentation for the feature they want to enable?

Good question. I'm not sure if we've tried to broadly answer in the general case. The Jakarta and MicroProfile APIs will largely will be covered with the "aggregate" dependencies like:

        <dependency>
            <groupId>org.eclipse.microprofile</groupId>
            <artifactId>microprofile</artifactId>
            <version>4.0</version>
            <type>pom</type>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-api</artifactId>
            <version>8.0.0</version>
            <scope>provided</scope>
        </dependency>

but that doesn't cover non-spec/platform features and I'm not sure what our general doc is.

[dmuelle]

Hi @scottkurz @yeekangc @mbroz2 , Here's the initial draft of the Betas doc:

https://draft-openlibertyio.mybluemix.net/docs/latest/installing-open-liberty-betas.html

This was based mostly on the beta blog post template, with some edits per Scott's comments. A couple questions:

• In the beta template and this draft, we only mention declaring dependencies for beta APIs in the Maven config- do we need a similar example for Gradle?
• Is the syntax in the example build.gradle dependency correct? The version depedency syntax looks weird to me, but I'm not familiar with Gradle and I couldn't find an alternate example from the Liberty gradle plugin to verify it against. The first bracket is square and the second is a parentheses. Also a comma after the value, but nothing further in the list.

dependencies {
    libertyRuntime group: 'io.openliberty.beta', name: 'openliberty-runtime', version: '[21.0.0.4-beta,)'
}

Update- @ericglau tested and confirmed confirmed the gradle syntax- all good.

Let me know what else this needs- thanks!

[scottkurz]

@dmuelle looks pretty good to me, and thorough !

A couple nits:

1. The wording in: For any beta features that are associated with either MicroProfile or Jakarta EE,

• If this is the term we use, then fine.. but "associated with" seems a bit loose, too broad. I'd have written something like "For any beta features for APIs included in either the MicroProfile or Jakarta EE platforms".

2. Maven config is fine, let me suggest though the latest config and removing the example server name which seems to me random unless there's a reason for it.

<plugin>
    <groupId>io.openliberty.tools</groupId>
    <artifactId>liberty-maven-plugin</artifactId>
    <version>3.3.4</version>
    <configuration>
        <runtimeArtifact>
          <groupId>io.openliberty.beta</groupId>
          <artifactId>openliberty-runtime</artifactId>
          <version>21.0.0.4-beta</version>
          <type>zip</type>
        </runtimeArtifact>
    </configuration>
</plugin>

[Joseph-Cass]

I know it's just an example, but for the MicroProfile API dependency example, we should probably use <version>4.0.1</version> since <version>4.0</version> is broken: eclipse/microprofile#205

[dmuelle]

Thanks for the feedback @scottkurz @Joseph-Cass . I've updated the draft to address your comments:

https://draft-openlibertyio.mybluemix.net/docs/latest/installing-open-liberty-betas.html

Let me know if you see anything else that needs an edit- thanks!

[yeekangc]

LGTM. Thanks, @dmuelle!

[scottkurz]

LGTM

[mbroz2]

I'm good with it as well, but keep in mind that this section is a point-in-time statement and will likely need to be updated in the future if kept as-is:

For example, features that are Jakarta EE 9 compliant are previewed in the Open Liberty beta releases. These features give developers an opportunity to try out Jakarta EE 9 and understand what might be required to move their workloads to a Jakarta EE 9 compatible runtime.

Same is true for the section later that talk about the Jakarta EE 9 package.
I think it's fine to keep it as is, but we need to make sure we remember to update this documentation once we no longer have the Jakarta EE 9 beta package

Since there are two artifactId elements, I would recommend specifying which one:

If you want to install the Jakarta EE 9 Beta Features package instead of the All Beta features package, set the artifactId element under runtimeArtifact to openliberty-jakartaee9.

[dmuelle]

Good point, @mbroz2 . I wasn't sure whether to include the Jakarta EE 9 info/package, but it has been such a big focus in the. beta blogs, I didn't want to omit it. I can open a bug on our backlog to revise the doc once the beta package is no longer available.

I updated the artifactID statement for clarification re runtimeArtifact.

One remaining question I have is whether we should provide an example to declare aggregate dependencies from Gradle context, as we have for Maven. Is there similar config a user would do to declare dependencies for MP or Jakarata in a build.gradle file?

[dmuelle]

Maven and Gradle config verified by @ericglau
@Rwalls1 think this is ready for content review now

[Rwalls1]

Content review

Try out new features with Open Liberty beta releases

I think you should provide a link to an official Jakarta EE 9 doc on first reference to provide necessary context since it is referenced throughout the topic

Install a beta features package

• I think you should change "Open Liberty offers two beta release packages, All Beta Features and Jakarta EE 9 Beta Features, both of which include everything from the most recent Open Liberty release.” to something like “Open Liberty offers the All Beta Features and Jakarta EE 9 Beta Features beta release packages that each include everything from the most recent Open Liberty release” to simplify the sentence by avoiding the use of multiple comma clauses.
• I think you should provide a link to Maven and Gradle official pages on first reference to provide more context about those tools.
• You should break the sentence "The All Beta Features package also includes all available beta features, while the Jakarta EE 9 Beta Features package adds only the beta features that are included as part of Jakarta EE 9.” into two sentences as it is currently longer and harder to read. So maybe change to something like, "The All Beta Features package also includes all available beta features. However, the Jakarta EE 9 Beta Features package adds only the beta features that are included as part of Jakarta EE 9.
• I think the phrases “beta release packages” and “beta feature package” are used interchangeably, which creates an inconsistency that could be confusing. In the first sentence of this section, you refer to “All Beta Features” and “Jakarta EE 9 Beta Features” as “two beta release packages”. However, throughout the rest of this section and topic, they are referred to as a “beta feature package”. I think you should address this by using the same term throughout to reference the packages.

Install a beta feature package package with Maven

• Typo: Change the title from “Install a beta feature package package with Maven” to “Install a beta feature package with Maven”
• I think it might be helpful to add another sentence or two that describes how the runtimeArtifact element installs the “All Beta Features” package or how it works with the plugin. The current description of the config example does not explain how the plugin actually uses the runtimeArtifact to install the package. What is a runtimeArtifact? If this detail is intended to be beyond the scope of this doc then I think you should reference another resource that might provide more detail. I don’t think anything similar is mentioned in the guide that is referenced.

[dmuelle]

Thanks for reviewing @Rwalls1- I made the following changes per your review:

• refer to feature packages consistently as "beta features packages", not "beta release packages"
• revised intro sentences to "Install a beta features package" section
• added links for more info about runtimeArtifact and Liberty maven and gradle plugins
• added links for Jakarta EE9, Maven, and Gradle
• fixed typo

[ManasiGandhi]

@dmuelle, I peer reviewed your topic.

Peer review

Try out new features with Open Liberty beta releases

• Could you add more context to this sentence “For example, features that are Jakarta EE 9 compliant are previewed in the Open Liberty beta releases.”? “previewed in the Open Liberty beta releases”, do you mean that the features can be previewed prior to Jakarta EE9? Also, the term “compliant” seems to be rarely used in documentation, could you replace it with “compatible”?
• “Beta releases are not intended for in-production use and some updates from the beta are never included in a production release.” Avoid the use of the term “never”, instead you could say, “Beta releases are not intended for in-production use and some updates from the beta might not be included in a production release.” Also, if you could move this second sentence to the beginning of the paragraph. The first and third sentences are related , as they provide info on how and why the “feedback from the user community about proposed updates” is helpful.

Install a beta features package with Maven

• “For more information about the runtimeArtifact element, see the Archetypes section of the Liberty Maven plug-in documentation.”, the link in this sentence goes to GitHub. Will it be eventually linked to a topic in OL?
• “For more information about using Maven with Open Liberty, see the Building a web application with Maven guide and the Liberty Maven plug-in documentation.” Remove the link from “documentation”.

Install a beta features package with Gradle

• “For more information about using Maven with Open Liberty, see the Building a web application with Maven guide and the Liberty Maven plug-in documentation.” Remove the link from “documentation”.

[dmuelle]

Thanks for reviewing @ManasiGandhi - i made the changes from your comment-
https://docs-draft-openlibertyio.mybluemix.net/docs/21.0.0.5/installing-open-liberty-betas.html

For the link to the Maven archetypes section- this doc is maintained in github because it's written and maintained by the dev team. I'm not aware of any plans to move it to the OL docs at this time

[dmuelle]

changes sent to vNext, will publish with 21.0.0.5