RFC: [PSR-5] @deprecated syntax could be better
photodude opened this issue · comments
The proposed PSR-5 @deprecated syntax could be better. The current syntax suggests using a single-colon for separating the 'starting version' (version in which the associated element has been deprecated) and the 'ending version' (the version in which the associated element is scheduled for removal)
Examples from current PSR-5
/**
* @deprecated 1.0.0:2.0.0
*
* @deprecated :2.0.0
*/In my opinion, this single-colon notation is too easy to misread and too easy for people to at a glance misunderstand. I would prefer some other character notation that has more visual significance for separating the 'starting version' from the 'ending version'
I suggest that hyphen notation for a single line @deprecated, is an improvement over the single-colon notation.
Examples using hyphen notation
/**
* @deprecated 1.0.0-2.0.0
*
* @deprecated -2.0.0
*/I'm open to other options, that like hyphen notation, have more visual significance than the current proposed single-colon notation.
Hyphen could be a part of a version, like 2.0.0-beta1.
@rob006 That is definitely true, "Hyphen could be a part of a version, like 2.0.0-beta1". It's unfortunate that Semantic Versioning even allows a Hyphen as part of the pre-release version scheme. I personally prefer 2.0.0.beta.1 to the Hyphenated pre-release version scheme.
But that's not the primary point I'm trying to bring up. It's that the single-colon notation doesn't hold enough visual weight when reading to prevent misreading it. Choosing a new character could/would improve general reading.
Here is a non-exhaustive list of other options; I'm open to any options that have more visual significance than the current proposed single-colon notation.
| Alternative | Char(s) | example1 | example2 |
|---|---|---|---|
| Double colon | :: |
@deprecated 1.0.0::2.0.0 |
@deprecated ::2.0.0 |
| Forward slash | / |
@deprecated 1.0.0/2.0.0 |
@deprecated /2.0.0 |
| Double Forward slash | // |
@deprecated 1.0.0//2.0.0 |
@deprecated //2.0.0 |
| Backslash | \ |
@deprecated 1.0.0\2.0.0 |
@deprecated \2.0.0 |
| Double Backslash | \\ |
@deprecated 1.0.0\\2.0.0 |
@deprecated \\2.0.0 |
| Pointer | -> |
@deprecated 1.0.0->2.0.0 |
@deprecated ->2.0.0 |
| Tilde | ~ |
@deprecated 1.0.0~2.0.0 |
@deprecated ~2.0.0 |
| Hyphen | - |
@deprecated 1.0.0-2.0.0 |
@deprecated -2.0.0 |
| Underscore | _ |
@deprecated 1.0.0_2.0.0 |
@deprecated _2.0.0 |
| verbose words | since #.#.# for removal in #.#.# |
@deprecated since 1.0.0 for removal in 2.0.0 |
@deprecated for removal in 2.0.0 |
Seems like this idea for a version range was itself a new idea when PSR-5 was being formulated, so it's possible that the usage isn't really out there in the wild yet. I'd be fine with considering another character if so.
Ping @ondrejmirtes @muglug @neuro159 @mindplay-dk @GaryJones @mvriel @jaapio for opinions.
I don't see why you would like to add this feature to this tag at all. This tag is an annotation to specify that a certain element will be removed in the future. It is unclear to me what the intention of the version in the deprecated tag means. Is it the version that will remove an element?
Why would you standardize something that can be part of de original tag? It is up to the user what to write in the description.
The default "ending version" would presumably be the next major version, if using semver, so it seems this extra syntax would only be useful if either the project didn't follow semver, or they were deprecating something several major releases in advance. Other projects may deprecate, but never remove.
Out of all options presented above, the single colon still looks most natural and most compatible.
Double colon could be an accepted alternative? We can allow both a single colon or a double colon?
My preference would be to drop the notion of the ending version altogether. Will wait for additional comments from working group and contributors.
What is expected workflow for these? Who and when actually looks at whats affected?
eg. I plan to update/just updated a dependency - run batch inspection for deprecation it before/after?
(replace batch inspection with CI/Linter check if its your case)
@photodude , if you wish to pursue this further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig