Responding to a question from@jklymak in#24160, I think we should be on the liberal side of adding these notes. It seems like we get ~ a bug report per month of "Why doesn't this documented feature work?!" to which the answer is "it was added in a newer version than you have installed. If the docs clearly say what version the feature was added in hopefully we can reduce that user frustration.

That said, having the version switcher on the docs does help make it easier to see the docs for the version you have installed.

If we get to a point where we have so many of these where it is distracting, my knee-jerk thought is to start removing 3-4 version of markers to keep the total number down...

That's fine with me. Otoh we need to be explicit about what is new if we do this for api changes.

Should we also have some removal policy? I guess the documents may be a bit unreadable if version info for every change since 2004 would be in there...

I'd go with Tom's suggestion. We should start thinking of removal, when it get's too distracting. But that can be decided when we're there. Guessing up-front is not necessary.

Agreed. Missed that comment though...

Since this is not only documentation but sets a policy, I'd like to have a second review.

@timhoffm question from#24160 - do we want to explicitly state whether the directives should be blank or give some context or leave that as a case by case?
ETA: Also thanks!

@story645 I've replied here:#24160 (comment)

Um should there be a placeholder letter instead of 3 too or not worth it for now?

Um should there be a placeholder letter instead of 3 too or not worth it for now?

This is clear enough. Let's not overthink this. (IMHO people would understand all ofX.Y,3.N,3.6)

IMHO people would understand all of X.Y, 3.N, 3.6

So leaving it here as 3.N to be consistent but b/f#23941 we were using X.Y. as minor.patch and now I'm tempted to make a follow up PR that just spells these things out asmajor.minor.patch throughout the dev docs

I'm not in favor ofmajor.minor.patch because that is quite verbose and it's less clear that these are variables.

If anything I have a slight preference for the concrete example.. versionadded:: 3.6. - People are able to generalize from that and won't copy literally. Generalizing seems a bit simpler that guessing what a variable should be. But as said

Let's not overthink this. (IMHO people would understand all ofX.Y,3.N,3.6)