Misleading description of secondary variants

[lukebemish]

Issue type

Wrong or misleading information

Problem description

The page on understanding variant selection is about the only place secondary variants seem to be documented, and has the following to say about them:

It also shows secondary variants, which are exclusive to Gradle projects and not published. For example, the secondary variant classes from apiElements is what allows Gradle to skip the JAR creation when compiling against a java-library project.

Additionally, the output from the outgoingVariants task has the following:

(*) Secondary variants are variants created via the Configuration#getOutgoing(): ConfigurationPublications API which also participate in selection, in addition to the configuration itself.

Between the two of these, I inferred that one can make a secondary variants through configurations.myConfiguration.outgoing.variants and that it will not be published; however, this is not the case. Secondary variants created that way appear to be published by default -- for a very simple case reproducing this, see https://gist.github.com/lukebemish/5b79f393c6a44e31311a8b8f18844c9c

Context (optional)

No response

Page with the problem

https://docs.gradle.org/current/userguide/variant_model.html

[ljacomet]

This is a valid documentation issue.

---

One way to think about secondary variants: they are pre-computed artifact transforms. They obey the same rules as artifact transform selection.

Related:

• Undocumented behaviour: Configuration secondary variants inherit the primary's attributes #28811
• Please improve variant/attribute documentation / error messages #12126

[lukebemish]

Thank you; That was my understanding of them too -- the specific issue with the docs is that they imply that secondary variants are not published, when in fact secondary variants are, without extra logic to exclude them, published alongside the "normal" variant.