Document new multi-pkg migration functionality

[h-vetinari]

Neither #6013 nor regro/cf-scripts#2706 document anything. I had asked for clarification in #6013 a couple days ago. CC @isuruf

AFAICT from scattered comments (and tests in regro/cf-scripts#2706), the intention is for the migrator bot to populate the migration yaml with all respective keys?

If so, why not do the broadcast from packages_to_migrate_together.yaml when applying the migrator, rather than when creating it? That way it would suffice to simply set one version in the migrator.

[isuruf]

If so, why not do the broadcast from packages_to_migrate_together.yaml when applying the migrator, rather than when creating it? That way it would suffice to simply set one version in the migrator.

You mean add new functionality to the already fragile variant algebra in conda-smithy?

[h-vetinari]

I mean: shift (or copy) the same logic as currently done to populate the bot migration yamls to be applied after reading a given migrator yaml, before any variant algebra is applied.

That way it would be possible to manually open migration PRs for the affected coupled libraries with setting only the top-level key, rather than restrict the benefit of broadcasting to only bot-generated PRs.

As a side benefit, it would be possible to update the broadcast relationship in the same PR as a new migrator, rather than being forced to do everything manually or wait for the bot.

[isuruf]

Sounds too complicated. Simpler the better.

[h-vetinari]

It's exactly as complicated as the current setup, just that the logic gets applied in a different place.

[isuruf]

From a maintainer perspective, it is. Currently you look at a migration file and you know what is being changed. With your suggestion, there's another layer of indirection that a maintainer has to be aware of and check.

[hmaarrfk]

I do like the fact that the migrator files are "fully detailed" and don't require any additional indirection.

Personally, I even find the global pinning file like "alot" of indirection but I'm glad that the version is written in the commit message.