search

OpenLiberty / docs

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

The Open Liberty version in which features were introduced into Open Liberty #2500

Open lauracowen opened 4 years ago

lauracowen commented 4 years ago

Observed problem:

Graham:

I sometimes get asked [by Liberty support customers or by IBMers] when a feature went into OL, and the Liberty Repository info on the right really helps with that.

The Liberty Repository currently displays this info on each feature's page: image.png Graham:

the 'from' release is most useful [as in the KC, rather than the date as shown in the Liberty Repo].

Also, the Java SE version compatibility info (as shown in the Liberty Repo) could be considered for inclusion too. Graham:

SE versions has been useful in the past and may continue to be. For example historically some EE feature would only work on a later Java. Jakarta EE 10, for example, might mandate Java 11, but we would still be supporting Java 8 with older features.

Possible solutions

Two solutions I could think of. I think enhancing the generated feature docs rather than creating a separate doc topic would be better. Would consolidate all info about a given feature in a predictable single place.

Would need to talk to Chuck/Michal/Alasdair

Solution 1. Enhance generated feature doc to include such info

We could insert that info into the generated feature docs, either during the initial generation or using includes (but would need to be automated so that it could be maintained).

Would need to talk to Chuck/Michal/Alasdair.

Solution 2. Create a separate reference topic for OL docs

Consider a reference topic that's a greatly simplified version of this KC topic: https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/rwlp_feat.html

NottyCode commented 4 years ago

The generated feature documentation already lists the supported Java SE versions.

The from information isn't there, but we aren't able to generate that since we don't actually know anything other than it was in the current release, we don't know about prior ones. Perhaps this would be simpler put into a manual include.

mbroz2 commented 4 years ago

If we were to provide the OL release version for the first time each feature become available, then yes, I think it would be done via includes (the tags that are already planned to be added for the generated content would enable this for the feature content in docs-generated (currently in docs), and the actual content for the corresponding release would be in docs repo).

However, given the amount of work that it would take to add it (158 places), given that we want people to take the latest version as often as possible, and given that this would resolve itself in time (we plan on only keeping at most 2 years worth of versions of docs on ol.io, and it would be as simple as switching to a particular version of the doc to see if the feature exists in that version, and if it doesn't exist in a particular version we have a work item to display the versions it does exist in), I'd question whether we want to invest resources in adding this information.

Charlotte-Holt commented 4 years ago

@gcharters Regarding Michal's comment, what's your take on how important it is that we have this information included in the feature docs?