docs: discourage main-subpackage name collisions for multiple outputs: in define-metadata.rst

[dlaehnemann]

Description

This is an attempt at correcting a misleading wording and providing good guidance for the naming of subpackages when using multiple outputs: in a meta.yaml recipe.

For cross-reference, this docs change was noted as being necessary in previous issues:

• Using same name in main package and outputs causes all kinds of problems, e.g. tests won't get run #3313 (comment)

Also, the previous wording implied that having the top-level name of a recipe repeated in one of the subpackage names. This is exactly the behavior that is cited to cause the unintended side-effects, for example here:

• Multi-output recipes might not run test suite in certain cases #4172 (comment)
• Run environment is cleared when multiple outputs are present #3337 (comment)
• conda build 3.16.3 does not handle pin_compatible correctly for multiple outputs #3277 (comment)

Feel free to further improve the wording, this is mostly meant to get the ball rolling again. Especially since previous efforts to make this name re-use a hard error in conda-build have all gone stale, see for example:

• give an error when trying to use the same name for the package and an… #3314
• Multi-output recipes might not run test suite in certain cases #4172
• Using same name in main package and outputs causes all kinds of problems, e.g. tests won't get run (take two) #5715

So this is kind of the minimal fix, something like #3314 would be much nicer in the mid-term. And I guess that in the long-term, this should go away if the new recipe format is fully implemented and enforced, see:

• add cep for definition of new keys & values in build format ceps#56
• https://conda.org/learn/ceps/cep-0014/

Checklist - did you ...

• Add a file to the news directory (using the template) for the next release's release notes?
• Add / update necessary tests?
• Add / update outdated documentation?

[conda-bot]

We require contributors to sign our Contributor License Agreement and we don't have one on file for @dlaehnemann.

In order for us to review and merge your code, please e-sign the Contributor License Agreement PDF. We then need to manually verify your signature, merge the PR (conda/infrastructure#1181), and ping the bot to refresh the PR.

[jezdez]

@conda-bot check

[dlaehnemann]

Just uncovered this older investigation of mine that I had lost track of. So ping @jezdez, I guess?

[dlaehnemann]

New year's ping @jezdez, while this is still on my radar. Hope you are back from happy holidays once you read this.

[ryanskeith]

Thank you for the addition of this warning.