Document that Java libraries should not have --allow-incomplete-classpath in their native-image.properties

[ppalaga]

The native image docs says

--allow-incomplete-classpath: allow the image build with an incomplete class path. Report type resolution errors at runtime when they are accessed the first time, instead of during the image build.

The statement does not put the option into the right context. For example library maintainers may think that it is a good idea to add --allow-incomplete-classpath to their native-image.properties thus enabling it for everybody depending on their library.

I think the docs should state that

• The option is intended mainly for debug purposes
• The option should generally not be present in native-image.properties of libraries intended for consumption by third parties.

It would be nice to have this documented when reporting issues like GoogleCloudPlatform/native-image-support-java#141 or arangodb/arangodb-java-driver#397

[christianwimmer]

We have the plan to make --allow-incomplete-classpath the default, and instead provide an option to enforce a "complete" classpath per library / package. See also the discussion in #2762
I hope to get that done for the 21.3 release.

So I don't think it is necessary right now to fight for library maintainers to not specify --allow-incomplete-classpath - especially since there is no per-package option yet that we could tell them to use.

[ppalaga]

Thanks @christianwimmer, commented there.