Retrieving docs about the pom.xml options is hard

[lauracowen]

I've tried using the ci.maven docs several times and I really struggle to find the info I need. But it's really hard to articulate the problem...so I'll give it a go but I'm happy to chat more if someone can take a look at this.

1) I think part of the problem is that the ci.maven docs assume intimate knowledge of the Liberty runtime options. I don't think it's your responsibility to provide reference docs for Liberty itself but it would help if you could provide links to the relevant KC topics (eg descriptions of all the packaging type options so that I can see a list of what all the options are and decide which I need.)...which brings me to....

2) Looking up something from my pom.xml in the docs is really hard. I didn't write the original POM so I don't know exactly what all the parts are for but I can't find the docs that describe them. I don't really understand all the Maven terminology and concepts (which may not help but I don't think I should be a Maven expert from the word go to be able to use a Maven plugin).

For example, I'm looking for all the packaging values I could use so I can decide which one I need. I don't know where in the ci.maven docs to look. There's a Packaging Types link on the first page of the docs but it doesn't take me to what I need - I think it's talking about packaging in a Maven sense rather than a Liberty sense, which doesn't help but that's not really the problem. The problem is that I have no idea where to look in the docs. Everything seems to be organised by Maven goal(?) but I have no idea what that maps to in the pom.xml structure. I just know that I'm looking at the <properties> section of the POM and I want to know what options I have available to set in there.

Or, say, I'm trying to work out why I keep getting the version number suffixed on to package file names (eg GettingStarted-1.0-SNAPSHOT.jar). I previously had a <package.file> setting set but then something else didn't work. These are frustrating problems and Maven is not the easiest thing in the world to debug, but I can't find the docs relevant to the bit of the POM I'm looking at to even start to work it out.

[chyt]

Hi Laura, so we worked out your issue with the package name over chat, so I think that's resolved.

I just know that I'm looking at the <properties> section of the POM and I want to know what options I have available to set in there.

You're right about the <packaging>, that is a Maven thing rather than a Liberty thing. <properties> are basically variables that can then be used anywhere else in the pom. There are also some properties that have special meaning to Maven or to certain plugins, but I don't believe that the Liberty Maven Plugin uses any of those.

The problem is that I have no idea where to look in the docs. Everything seems to be organised by Maven goal(?) but I have no idea what that maps to in the pom.xml structure.

So that can be a bit confusing if you're using liberty-assembly as the packaging type or the parent pom. When you're using either of those things, a bunch of goals are being added to your build automatically, but they are not actually visible in your pom.xml. You will have to run a mvn help:effective-pom in order to actually see the goals that are added. By looking at the effective pom you can get a clearer idea of which configuration is being applied to which goals.

I think part of the problem is that the ci.maven docs assume intimate knowledge of the Liberty runtime options.

This is a big problem that we have, and a very valid one especially since we're migrating this repository to the Open Liberty Github. I don't think it's appropriate to link users to the knowledge center if we are advertising that this plugin be used with Open Liberty. I also agree that we should not be putting the docs on Liberty itself in this repo.

I think that ideally, there need to be some docs on openliberty.io about Open Liberty that we can link to. Aside from us pointing to it, that would also be helpful to promote Open Liberty. Right now there's nothing on the site that gives a clear picture of why people should use Open Liberty or the advantages that it has over other app servers. For example, loose application is a big feature of Open Liberty, and we talk about it a ton in the docs, but there's no dedicated page on ol.io that explains what loose app is in detail (I think it is mentioned briefly in a few guides though).