Feedback on https://jquery.com/upgrade-guide/4.0/

[davidearl]

(a) it still says jquery 4 not yet released

(b) Under 'Summary of Important Changes' , you say "Deprecated: This feature or API is still present in jQuery 3.0, but its use is discouraged. It may be removed in a future major-version update.". I think you may mean jQuery 4.0 (3.0 carried over from previous version of this doc?)

(c) more importantly, under 'Breaking change: px no longer automatically added to most unitless values', you say "jQuery will now only add px to a limited set of properties that are known to require it. ". It would be very helpful indeed to include a list of these here. I asked claude.ai and it came up with the following, which seem plausible, but it's hard to vouch for its reliability...

Position properties:

top, right, bottom, left

Dimension properties:

width, height
min-width, min-height
max-width, max-height

Padding properties:

padding, padding-top, padding-right, padding-bottom, padding-left

Margin properties:

margin, margin-top, margin-right, margin-bottom, margin-left

Border properties:

border-width, border-top-width, border-right-width, border-bottom-width, border-left-width

This is a significant change from jQuery 3.x, which used a "blacklist" approach and automatically added px to almost everything except properties like opacity, z-index, font-weight, etc. jQuery 4 flips this to a "whitelist" approach, so any CSS property not in the above list will need explicit units when you pass numeric values.
For all other properties (like font-size, line-height, z-index, opacity, flexbox properties, grid properties, etc.), you'll need to provide the units explicitly as strings, e.g., $el.css('font-size', '16px') instead of $el.css('font-size', 16).

(d) It would be helpful to briefly understand the knock on effects on "jquery ui" if any, even if only a referenbce as to where to look re relationship between jquery 4 and jquery ui. When I did a search of my code, it picked up some occurrences of jQuery.isArray and $.unique for example, but I have no idea whether these are significant or not, and I am probably using in older version anyway.

[timmywil]

Thank you! Indeed the guide needs some updates.

On (c), I think the more important point is that we want to encourage users to always add their own units, so a list of properties where the behavior may still exist would not be related to the proposed migration. Also, the list may change so I'd rather not cause confusion with a list that may get out of date.

For (d), jQuery UI already has an update (1.14) that makes it compatible with jQuery 4. All usage of deprecated APIs has been removed. I think an update to the jquery ui homepage is in order, but I don't think it warrants a mention in the jQuery Core upgrade guide.

[davidearl]

Hmm, but functions like offset and position return pixels, so it is not unreasonable to want to get a number, do a calculation and then set it back again. It's asymmetric otherwise. Also, means int to string conversion as in `{$w}px`, though presumably jquery does that inside anyway, though in one place, not many . And more importantly, I have hundreds of these which finding and changing would be just awful, such a waste of time.

As it stands, though, I have no reliable way of telling what I should change and what not, so you might as well say everything must have units, if you're not prepared to say which ones. Or you could also say all or some of them are going to be deprecated in version 5. As it stands it just isn't helpful to say "hey we didn't do it in all cases, but you have to guess which", which is what it amounts to.

[timmywil]

The migrate plugin can help with all of that. Also, the change doesn't affect offset and position.