search

OpenLiberty / docs

See Open Liberty documentation on https://openliberty.io/docs/
https://openliberty.io/docs/
Other
13 stars 47 forks source link

Document Liberty Tools for MVP #5823

Closed dmuelle closed 1 year ago

dmuelle commented 2 years ago

We need an overview page for the new Liberty Tools for Eclipse, VS Code, and Intellij.

Planned MVP Ga is December 9th. Doc will publish with 22.0.0.13

yeekangc commented 2 years ago

Need to link out to marketplace entries for the tools as well.

dmuelle commented 1 year ago

comment from slack discussion: Does Liberty Tools support EE8 and MP4? Determine by pom.xml or server.xml? This should be at the top of our doc. I don't believe we offer any assistance with EE 8... @Kathryn Kodama or @tcrawford please correct me. For MP 4, since it's the same classes as MP 3, I believe you can make use of the LS, as long as you stick to the MP 3 subset.

kinueng commented 1 year ago

The openliberty.io work item for the new IDE tools section

dmuelle commented 1 year ago

@cherylking @yeekangc @TrevCraw @scottkurz @kathrynkodama

The initial draft of the Liberty Tools overview is now available for review

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/develop-liberty-tools.html

Please leave any feedback as a comment in this issue- thanks!

kathrynkodama commented 1 year ago

@dmuelle A few suggestions, feel free to disregard any:

General comments:

yeekangc commented 1 year ago

Thanks!

dmuelle commented 1 year ago

Thanks @yeekangc @kathrynkodama , all comments addressed in the refreshed draft:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/develop-liberty-tools.html

a few notes:

kathrynkodama commented 1 year ago

@dmuelle In the second paragraph, this sentence: "Liberty Tools automatically detects any projects that specify the Liberty Maven plug-in or the Liberty Gradle plug-in in the project pom.xl file." needs to be updated to: "Liberty Tools automatically detects any projects that specify the Liberty Maven plug-in or the Liberty Gradle plug-in in the project's pom.xml or build.gradle file."

Not sure if this is too much detail or whether we should call this out here, but the tools will detect Liberty projects that have a src/main/liberty/config/server.xml file and we expect that they have the Liberty plug-in specified in their build file.

cherylking commented 1 year ago

Shouldn't it actually be detect instead of detects...Liberty Tools is plural.

"Liberty Tools automatically detects any projects"

cherylking commented 1 year ago

Same in this sentence: "Liberty Tools also provides helpful language-support" Change provides to provide.

cherylking commented 1 year ago

And " Liberty Tools brings these"...change brings to bring. I'm the verb tense police today :-)

dmuelle commented 1 year ago

@cherylking - as a product name "Liberty Tools" is treated as a collective noun, ie the title is plural, but as a product it is a singular entity (though made up of component parts).

cherylking commented 1 year ago

@cherylking - as a product name "Liberty Tools" is treated as a collective noun, ie the title is plural, but as a product it is a singular entity (though made up of component parts).

ok, but it reads weird.

cherylking commented 1 year ago

Given that "Liberty Tools" is actually referring to three products, it seems plural and reads plural. But I will defer to your judgement.

kathrynkodama commented 1 year ago

One more suggestion - can we add to the "Jakarta EE APIs" section that the language features are delivered for Java files. Either at the top or after each bullet like in the "MicroProfile EE APIs" section?

dmuelle commented 1 year ago

@cherylking - I was thinking from the opening sentence definition

Liberty Tools is an intuitive set of developer tools....

When you talk about them collectively as a set of developer tools (or 3 plugins/extensions), that set is singular. However, It does seem awkward elsewhere in the topic and I think we can update to treat them as plural. Generally, brand names and product names are treated as singular but I can't find any explicit guidance that says never to treat them as plural.

could maybe in the intro just say

Liberty Tools are intuitive developer tools....

dmuelle commented 1 year ago

Thanks for reviewing @cherylking @kathrynkodama - all comments incorporated except

Not sure if this is too much detail or whether we should call this out here, but the tools will detect Liberty projects that have a src/main/liberty/config/server.xml file and we expect that they have the Liberty plug-in specified in their build file.

I don't quite understand- does this mean you get language server features as long as you have a src/main/liberty/config/server.xml file, but you'd need the one of plugins to interact with dev mode?

kathrynkodama commented 1 year ago

I don't quite understand- does this mean you get language server features as long as you have a src/main/liberty/config/server.xml file, but you'd need the one of plugins to interact with dev mode?

This might be too much detail for these docs, so maybe it is fine to leave as-is. The general recommendation is that users have the Liberty plugin already configured.

To get specific, the project will be populated in the dashboard/tool window if a src/main/liberty/config/server.xml file is detected. The tools assume that they have one of the plugins configured already. With Maven, even if they don't have the plugin configured, they will still be able to start dev mode (with the way we call the command). With Gradle, they will need to have the Liberty Gradle plugin configured for dev mode to start correctly.

The language server support works independently of the dashboard/tool window. Liberty Config language support will be delivered if one of the supported files is opened. Jakarta EE and MicroProfile API language support will be delivered on any Java file where we can detect usage of a Jakarta EE or MicroProfile API or a microprofile-config.properties file.

cherylking commented 1 year ago

@dmuelle So to sum up what Kathryn said, I think they will get Liberty language server features for their Liberty config files regardless of whether the LMP/LGP are configured.

dmuelle commented 1 year ago

ok- to firm up the minimum requirements section. Now we have

To use Liberty Tools with dev mode, your project must specify the Liberty Maven plug-in or the Liberty Gradle plug-in in the project pom.xl or build.gradle file. A minimum level of 3.7.1 for the Liberty Maven plug-in or 3.5.1 for the Liberty Gradle plug-in is recommended.

Language support features are available for MicroProfile 3.0 and 4.0 APIs and Jakarta EE 9.x APIs.

Maybe it should say

To use Liberty Tools with dev mode, your project must specify the Liberty Maven plug-in or the Liberty Gradle plug-in in the project pom.xl or build.gradle file. A minimum level of 3.7.1 for the Liberty Maven plug-in or 3.5.1 for the Liberty Gradle plug-in is recommended.

Language support features are available for MicroProfile 3.0 and 4.0 APIs, Jakarta EE 9.x APIs, and select Liberty configuration and Java files. These features are enabled for any Liberty project that includes a server.xml file in the src/main/liberty/config directory.

dmuelle commented 1 year ago

that elides a bit of detail but from a user perspective does it cover all the bases?

cherylking commented 1 year ago

Language support features are available for MicroProfile 3.0 and 4.0 APIs, Jakarta EE 9.x APIs, and select Liberty configuration and Java files. These features are enabled for any Liberty project that includes a server.xml file in the src/main/liberty/config directory.

That last sentence only applies to the Liberty config language server. So that is confusing. Makes it sound like you won't get the Jakarata and MP language server support unless you have a server.xml. I don't think that is correct, is it @kathrynkodama ?

kathrynkodama commented 1 year ago

@cherylking Right, it does not apply to the Jakarta and MP language support. They will provide support on any Java file that detects usage of the Jakarta EE and MP APIs

dmuelle commented 1 year ago

To use Liberty Tools with dev mode, your project must specify the Liberty Maven plug-in or the Liberty Gradle plug-in in the project pom.xl or build.gradle file. A minimum level of 3.7.1 for the Liberty Maven plug-in or 3.5.1 for the Liberty Gradle plug-in is recommended.

Language support features are available for MicroProfile 3.0 and 4.0 APIs, Jakarta EE 9.x APIs, and select Liberty configuration and Java files.

I guess we could say something like

To use the full set of Liberty Tools functions for dev mode, your project must specify...

scottkurz commented 1 year ago

OK, I'm a bit late to the game, sorry about that. Some of this has been said already but I'm basing my comments on the latest draft server even if there's some overlap

  1. pom.xl => pom.xml (this still appears twice)
  2. plug-in? I see this is indeed what this doc uses....it's just weird since Maven/Gradle generally use "plugin" and only Eclipse uses this "plug-in" but OK.
  3. Liberty Tools singular vs. plural - I see we had a bunch of discussion already. To me it looks weird to see it plural...most of the time users will encounter it as a singular entity in their IDE and not care about our collective effort.. but.. I'm late to the party and it doesn't look awful as a plural.
  4. In the "Minimum Requirements" sec. when we see the sentence: Language support features are available for MicroProfile 3.0 and 4.0 APIs, Jakarta EE 9.x APIs, and select Liberty configuration and Java files we just read essentially the same thing in the very first section so maybe could delete.
  5. "With a just few clicks" => "With just a few clicks"
  6. "Virtual Studio Code CodeLens support " you must have meant "Visual Studio Code CodeLens".... or is just "CodeLens" enough? I might read this and think it doesn't apply to Eclipse....but if this is the better common name fine.
  7. The Liberty Tools Eclipse IDE Eclipse Marketplace link is now live at: Liberty Tools Eclipse link: https://marketplace.eclipse.org/content/liberty-tools
scottkurz commented 1 year ago

One more detail:

These features are available for the following Liberty configuration files
...
Any XML files that contain the server root element and exist in the src/main/liberty/config, configDropins/overrides, configDropins/defaults, usr/shared/config, or usr/servers directory

I don't think that accurately describes the current story....e.g. a src/main/liberty/config/my.xml won't get the LCLS XML support. @cherylking correct me if I'm wrong. Maybe we could just say less and it'd be close enough. Was there already a comment on this?

cherylking commented 1 year ago

I don't think that accurately describes the current story....e.g. a src/main/liberty/config/my.xml won't get the LCLS XML support. @cherylking correct me if I'm wrong. Maybe we could just say less and it'd be close enough. Was there already a comment on this?

I think it will get support. I will have to verify, but we look for other xml files in the pre-defined config locations for Liberty in addition to any xml file <include> from the server.xml.

dmuelle commented 1 year ago

Thanks for reviewing @scottkurz - I made the following changes-

  1. fixed instances of pom.xl
  2. "plug-in" - this is the spelling IBM terminology recommends and also what we use elsewhere in the Open Liberty docs
  3. Liberty Tools singular vs. plural- I'm still not 100% sold on them being plural- though I agree with Cheryl that having them singular was awkward in parts of the doc.
  4. removed redundant language support info from the minimum requirements- its mentioned in the intro and detailed in the language support section. Also not technically a minimum requirement for using the tools
  5. fixed ""With a just few clicks"
  6. Changed VS CodeLens to be just CodeLens- I didn't realize this was available in eclipse as most references on the web only mention vs code. Is it valid for Intellij?
  7. added eclipse marketplace link

I left the supported files list as is based on Cheryl's response- can update if needed.

cherylking commented 1 year ago

@dmuelle Maybe it would be safer for now to take out the line about the additional XML files in those config folders. We can add it later once we figure out whatever bug we have in that section of code.

cherylking commented 1 year ago

@dmuelle After some testing, I think the line just needs to be altered slightly from:

    Any XML files that contain the server root element and exist in the src/main/liberty/config, configDropins/overrides, configDropins/defaults, usr/shared/config, or usr/servers directory

to 

    Any XML files that contain the server root element and exist in the configDropins/overrides, configDropins/defaults, usr/shared/config, or usr/servers directory
dmuelle commented 1 year ago

@cherylking - updated Liberty config XML file list https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/develop-liberty-tools.html#_liberty_configuration_files

dmuelle commented 1 year ago

Thanks to all for your work on the overview doc for the early release refresh, it is now published at

https://openliberty.io/docs/latest/develop-liberty-tools.html

I'm going to keep this issue open at the moment to track related ID updates in the various Git repos. Here is the progress on those so far:

IntelliJ and VS Code: edited and published the Git docs, including the README, user guide, Developing, Contributing Eclipse: awaiting updates LCLS: Docs edited and updated LSP4Jarkarta: Docs edited and updated

We can also use this issue to track any changes needed between the early release and GA

dmuelle commented 1 year ago

ID work for GA is tracked in #6403, closing this issue