Use hyphenated version directives

[stephenfin]

Purpose

We alias the versioning directives like so:

• version-added (was versionadded)
• version-changed (was versionchanged)
• version-removed (was versionremoved)
• version-deprecated (was deprecated)

The original names are marked as deprecated in the docs but do no produce build-time warnings, since we don't want to break 1000s of builds using -W (warning is error) over this.

(edit: updated since creation to reflect changes in PR)

References

(none)

[timhoffm]

Is this really worth it? Yes, consistency is nice, but I’ve used all these directives and I’ve never stumbled on the naming; .. deprecated:: felt quite natural to me. I actually find .. versiondeprecated:: harder to read and type.

If this is added, I’d at least not deprecate deprecated. Instead, keep both, either as equivalent, or with a recommendation for one. Announcing that deprecated is deprecated will push users into updating because it implies that it will be removed in the future, and I think we should not burden users with this. If you instead state a preference only, new code will use it. Since deprecated statements will by-design be removed after some time, code bases will evolve naturally into the new state, and then deprecating deprecated at some point in the future has much smaller effect.

[stephenfin]

Is this really worth it? Yes, consistency is nice, but I’ve used all these directives and I’ve never stumbled on the naming; .. deprecated:: felt quite natural to me. I actually find .. versiondeprecated:: harder to read and type.

Is it needed? No. But it's helpful to have the set of versionadded, versionchanged, and versionremoved. An alternative would be to provide added, changed, and removed aliases (or introduce hyphens to all).

If this is added, I’d at least not deprecate deprecated. Instead, keep both, either as equivalent, or with a recommendation for one. Announcing that deprecated is deprecated will push users into updating because it implies that it will be removed in the future, and I think we should not burden users with this. If you instead state a preference only, new code will use it. Since deprecated statements will by-design be removed after some time, code bases will evolve naturally into the new state, and then deprecating deprecated at some point in the future has much smaller effect.

I agree. That's my intention in only noting it in the docs: I specifically did not want to create busy work for people.

[AA-Turner]

I'd be happy to add alternative forms with a hyphen, we've done this already for various directive options (no-index, etc). Otherwise I'm ambivalent -- the shorter forms (.. addded::) seem cleaner, but the existing ones are clearer about what they describe.

A

[stephenfin]

I'd be happy to add alternative forms with a hyphen, we've done this already for various directive options (no-index, etc). Otherwise I'm ambivalent -- the shorter forms (.. addded::) seem cleaner, but the existing ones are clearer about what they describe.

Sure. Done.

[timhoffm]

IMHO the hyphened version is a readability improvement. OTOH it is a massive change. I'm +0.5 overall., but I leave it to @AA-Turner to do the tradeoff.

Concerning the PR: I suggest to split the actual change documentation and announcement from the mass-update. - At least by commits, but possibly even into separate PRs. First lets get the documentation and communication right - this is a small change but needs care to detail, because this change eventually affects a significant part of our users. Then, let's do our internal cleanup, which is a lot of churn but mostly a trivial replacement.

[stephenfin]

IMHO the hyphened version is a readability improvement. OTOH it is a massive change. I'm +0.5 overall., but I leave it to @AA-Turner to do the tradeoff.

I think the fact that we are not deprecating (in code) - and IMO should never deprecate - the older mechanism would limit the fallout of this. Newer docs can benefit from improved readability but older docs continue to work.

Concerning the PR: I suggest to split the actual change documentation and announcement from the mass-update. - At least by commits, but possibly even into separate PRs. First lets get the documentation and communication right - this is a small change but needs care to detail, because this change eventually affects a significant part of our users. Then, let's do our internal cleanup, which is a lot of churn but mostly a trivial replacement.

I've mostly done this already, but I can remove the outstanding changes to doc (a hangover from the previous revision of this PR, when we were only replacing deprecated with versiondeprecated) if helpful