Actually @efiring argued in #12383 (comment) against the s->text change; I personally don't really mind either way and can revert it here if that's the agreement.
Note, though, that right now it's plt.text(x, y, s) but Text(x, y, text); they should be made consistent.

Looks like it interacts with pyplot in a bit of a weird way too...

Regarding my earlier comment in favor of "s": I'm willing to back off on that. It probably does make more sense at this point for annotate to match the Text API and use 'text'.

I see your point @tacaswell re: pyplot. I think everything can be made to work, just needs a bit more care...

Went for a different, and in fact much simpler implementation (turns out the pyplot wrappers really constrain the design space here).

Could you also add a make_paramaters_after_N_kwarg_only as a decorator?

That's actually going to be harder wrt. the pyplot wrappers, I think(?), because that decorator probably really needs to be applied on the wrapper as well (as the wrappers pass everything down by keyword, so the inner function cannot check whether the argument was passed positionally to the wrapper), and I tried quite hard (both here and in #13173) to not "store additional information" on the method to tell whether the wrapper needs additional decorators.

Edit: IIRC we can't make the pyplot wrappers just take *args, **kwargs and forward them as such to the axes methods because jedi/other autocompletion tools would hate us, but I guess we can add a decorator around each pyplot wrapper of the form

@pyplot_wrapper(gca, Axes.text)
def text(x, y, s, ...): return gca().text(x, y, s, ...)

with

def pyplot_wrapper(gca, method):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs): return method(gca(), *args, **kwargs)
        return wrapper
    return decorator

i.e. the decorator actually completely ignores the implementation of the wrapper and directly forwards the arguments to the method instead... now the method will know whether the argument was passed positionally or as keyword, and the "deprecate_passing_positionally" decorator will work.
Ugly, isn't it :)

I don't think it would be terrible for the pyplot generating code to be aware of our deprecation decorators to a sufficient degree that it could re-write them into the generated code. That would be nice for the humans who look at the code in pyplot.

On the other hand, reducing the bodies of the functions in pyplot to ... also seems appealing...

Now that I think of it, one main argument for moving to keyword-only arguments is to make it easier to rename or to delete arguments, but now that this PR and #13173 implement these features, I guess it's not that useful anymore?

This seems fine to me, but I don't think it should be merged unless @tacaswell and/or @efiring approve.

one main argument for moving to keyword-only arguments is to make it easier to rename or to delete arguments

I guess thats true, but I think its also better to make the interface explicit to get rid of the magic guessing we do about what each arg means.

Good to merge? :)

I'd like @tacaswell to merge.

I think we should also decide some sort of guidelines for renaming... Just because this is easier dosn't mean we should break old documentation and examples on webpages...

I think it should be treated as an API break like most others, although with a lower bar if we can reasonably assume that the parameter was rarely if ever passed as keyword (e.g. matplotlib.use(arg=...) is probably rare, whereas hist(normed=...) is fairly common (relative to the number of uses of hist())).

ping @tacaswell - I'll merge if don't hear from you by w/e

(force push: replaced "argument" by "parameter" in the changelog, for consistency with the decorator name, see also https://stackoverflow.com/questions/156767/whats-the-difference-between-an-argument-and-a-parameter)