Salt: [DISCUSS] use_superseded is confusing

[The-Loeki]

Description of Issue/Question

While I'm really enthousiastic about the functionality, I personally find the use_superseded name confusing linguistically;
as a non-native English speaker I might of course be very wrong, but it's my impression that DeprecatedX _is superseded by_ NewY.

Then I read

use_superseded:
  - module.run

as 'Use DeprecatedX', while it actually means 'Use NewY'.

@isbm / @cachedout am I wrong here? Is there such a thing as e.g. use_superseding and shouldn't we use something like that?

Refs

42260

42148

[isbm]

:wink: Not really.

The word "superseded" is a simple past tense and past participle of "supersede" which means "to replace". So "use superseded", same as "use replaced" which is in the same tense and participle (or "use newer" or "use latest" although these two would be more confusing by their etymology), and thus you are using newer version of it. Whilst "replaced" would be more simple for non-English speakers, it would be a wrong choice. The word "supersede" has been chosen due to its explicit etymology from Latin "supersedere", that consists of a) "super" or “over” and b) "sedere" or “to sit”, and its exact meaning of making previous item deferred and obsolete yet still available, which is different from the word "replaced".

Hope it helps & clarifies. :wink:

[The-Loeki]

LOL yes & no. Supersede == replace works for me, but any dict named use_replaced would suggest to me, again, that it triggers the ones that have been replaced rather than the replacees(?).

The syntax problem is that I (and by extension probably others) interpret this as a shorthanded adjective:
_'use (the) superseded (function):'_

while you're interpreting it as a past tense:
_'use (the function that has) superseded:'_

[The-Loeki]

I'm getting even more confused as even the adjective seems multi-interpretable :)

expanding on the one before, the difference can also be explained as

_'use overlaid function for:'_ which is pretty much where you're coming from or
_'use function that has been overlaid:'_ - which is pretty much where I'm coming from

again, my vote is to personalize the verb use_superseding prevents the confusion

[lorengordon]

I find the wording of this option confusing for exactly the same reason, and English is my first language. :/ I still actually can't figure out if this option means that I need to use the latest syntax in my states, or the prior syntax.

[isbm]

@lorengordon proposal?

[lorengordon]

@isbm, sure, I'll ponder on some options. But, which is it? If the function is specified in this list, does that mean I must "use the latest syntax" or that I must "use the prior syntax" in my states?

[isbm]

Essentially, this is a switch between:

• newer function implementation
• older function implementation

So you suppose to choose the _implementation_ of the same function:

useyourpreferredenglishforanewerfunction:
  yourmodule.yoursomefunction   # <-----------+
                                            # |
useyourpreferredenglishforanolderfunction:  # +----= these are the same!
  yourmodule.yoursomefunction   # <-----------+

I'd prefer "supersede" involved.

[lorengordon]

The implementation here is a completely new function, rather than different parsing of function arguments?

[isbm]

@lorengordon not necessarily. The name stays the same, but the difference can be _one of_:

• Output result with the different type/structure but the same parameters
• Same output, different parameters
• Both above differs from the predecessor

An example: uptime before was just dumping the Unix output as is. Now it returns parsed JSON (if you use the newer implementation). But it can fall-back if you pass an argument to it or system is weird, like an old AIX or IRIX.

[lorengordon]

So are there two options here? One for newer syntax/behavior and one for previous syntax/behavior? Only one option, use_superseded, has been mentioned so far, so I think I'm just getting more confused.

[isbm]

@lorengordon Well, there is a policy: default-in, default-out. That is, some functions by default old, so you need to turn on new if you want. Some functions are by default new, so you need to turn off them to revert the old behaviour. Hence you have to explicitly say "give me new" and "give me old".

[lorengordon]

Yeah, alright, this option is just waaay too confusing. I think I'd rather just watch my states fail and rewrite them than try to understand what this option is doing.

[isbm]

@lorengordon What is exactly confusing? You see in your log something like:

[WARNING]: The function 'foo.bar' is used in old way. Please use arguments X/Y/Z instead of A/B/C. It will be removed in version "Foobar".

So you:

1. Say to Salt: "Configure yourself to use newer foo.bar version
2. Rewrite your SLS the way it fits the _new_ syntax

Done.

[The-Loeki]

I completely agree with @isbm that supersede is the right term; after all we're proposing to activate a new function/syntax which is due to be deprecated and removed.
I've look around on the interwebs and superseding seems perfectly acceptable. I think therefore

@lorengordon :

use_deprecated:
  - state.module.wait     # default

use_superseding:
  - state.module.run

look much less confusing to you?

[isbm]

@The-Loeki I think I am going to agree with you. :laughing: But let me one step after another: the PR for bugfix you've opened the other hour I have to finish.

[The-Loeki]

I much prefer the "warn about impending doom while keep on running" paradigm to the "sudden death as part of upgrade" one. Especially salt needs to deal with these things as gracefully as possible ;)

[isbm]

@The-Loeki this is mainly why I invented all that stuff: for graceful API migration. But this is not that really easy, apparently... :disappointed:

[lorengordon]

@The-Loeki, yes, it helps seeing the two options side-by-side like that. Another pattern (from python), other than use_superseding, might be use_futures?

[lorengordon]

This should all be great fun when the current "superseding" function is itself deprecated...

[isbm]

@lorengordon :laughing: :laughing: Well, technically this is actually possible. In this case you will just never get the things in between:

@with_deprecated(globals(), "Oxygen", with_name="_veryoldfunc")
def newfunc():
    pass

@is_deprecated(globals(), "Oxygen", with_successor="newfunc")
def _abitnewer():
    pass

@is_deprecated(globals(), "Oxygen",  with_successor="_abitnewer")
def _veryoldfunc():
    pass

So therefore you always have no triple-nesting, but only old and new one. So no problems.

The whole purpose is to add a decorator nearby the function, instead of explicitly changing its docstring and modify its code. Also allows to replace functions, the same way as you update the city: building the new building on top of the old or leaving the outer walls for facade purposes, changing everything inside.