[Vote ended on 2024-07-02] Avoid using aliases for module options

[mariolenz]

I think we should discuss avoid using aliases. What do you think? At first glance, it makes sense to me.

[felixfontein]

I agree with this recommendation (and gave similar suggestions in quite a few reviews, and try to avoid them myself as well).

I think the main reason against aliases is that they can quickly lead to confusion: say you’re using both an option and an alias and don’t spot it immediately; or you and a colleague talk about a feature and you’re disagreeing of how it’s called, only to realize that one of you is using an alias.

There are also valid uses for aliases, so it’s definitely not a good idea to completely forbid them. But recommending to avoid them is still a good thing, to make folks at least think twice before adding a new one!

[mariolenz]

@felixfontein

There are also valid uses for aliases, so it’s definitely not a good idea to completely forbid them.

The PR doesn’t forbid aliases completely, it says:

Generally avoid using aliases.

Generally is important here

And it also says:

Consider using them temporarily in exceptional cases like typos or inappropriate words in the original argument name with deprecation and subsequent removal of the original one using the deprecated_aliases attribute.

So it still allows using aliases. The PR allows to use aliases if there’s a valid use case.

[sshnaidm (Sagi Shnaidman)]

Aliases are not added because of “bad naming”, it helps to manage compatibility during various changes. For example in Podman we have arguments that fit Podman args, which are VERY changing in time, but also tries to have compatibility with Docker args. And every other software changes its arguments with aliases, that’s a real life.
Misuse and abuse can destroy any good idea, it doesn’t mean the idea was wrong. I’m totally for deprecated_aliases shortcut though, which will save time of working on deprecation messages.

[flowerysong]

I think the idea of providing guidance around best practices for aliases is good, but I do not find the way it’s currently phrased helpful. I would go for something more like this:

Excessive use of aliases can make module interfaces confusing, so we recommend adding them only when necessary. If you are updating argument names to fix a typo or improve the interface, consider moving the old names to deprecated_aliases rather than keeping them around indefinitely.

[Andersson007]

@flowerysong

Excessive use of aliases can make module interfaces confusing, so we recommend adding them only when necessary. If you are updating argument names to fix a typo or improve the interface, consider moving the old names to deprecated_aliases rather than keeping them around indefinitely.

@flowerysong your wording SGTM, would you like to suggest the change in the PR so that you’ll be a co-author? If you miss this message anyhow, I’ll update it myself in a day or two. Thanks!

[Andersson007]

@SteeringCommittee and community please vote. The poll will end on 2024-07-02.

[Steering Committee poll] Merge the PR.

• Yes
• No

[Community poll] Merge the PR.

• Yes
• NO

[gundalow]

@sshnaidm

Aliases are not added because of “bad naming”, it helps to manage compatibility during various changes. For example in Podman we have arguments that fit Podman args, which are VERY changing in time, but also tries to have compatibility with Docker args. And every other software changes its arguments with aliases, that’s a real life.

This seems like a perfectly valid use of Aliases, thanks for sharing this example.

[mariolenz]

@sshnaidm

Aliases are not added because of “bad naming”

Sometimes they are. Let’s say they are not only / always added because of bad naming

I agree with @gundalow that your example is a valid use-case for aliases. But the text in the PR wouldn’t forbid this, would it? It says

adding them only when necessary

and in your example I think there’s a strong argument that it is.

[Andersson007]

Closed the polls and merged the PR, thanks everyone!