Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

jquery-patch.js: Misleading label and description ("Support version 1.8.x and newer of jQuery core") #2200

Open
Chealer opened this issue Nov 7, 2023 · 10 comments

Comments

@Chealer
Copy link

Chealer commented Nov 7, 2023

The jquery-patch.js component increases backwards compatibility by allowing current jQuery UI versions to be used with jQuery core versions anterior to 3.5 (until 1.8). jQuery core 3.5+ would otherwise be required, as explained in the Newer Core features section of the jQuery UI 1.13 Upgrade Guide:

As part of making sure jQuery UI doesn't depend on deprecated Core APIs, we started using some newer Core APIs, polyfilling them in the jquery-patch.js file for older jQuery versions. If you haven't included jquery-1-7.js in your bundle of jQuery UI 1.12.x, you may still need to include jquery-patch.js when migrating to UI 1.13.x; it's required for all jQuery versions older than 3.5.0.

Unfortunately, that is pretty far from what one understands when using the Download Builder, which calls it "jQuery 1.8+ Support" and describes its role as "Support version 1.8.x and newer of jQuery core".

This name and this description come from the label and description defined in the file's header. Even though the previous versions were poor/outdated, they became misleading and fragile when support for core 1.7 was dropped.

The new texts make it backwards, implying that jquery-patch provides compatibility with new versions, rather than with old versions. Moreover, it makes the information time-sensitive, as while they may not be quite wrong at this time, there is no guarantee that jQuery UI 1.13 will be compatible with jQuery core 4.

I suggest the following:

//>>label: Legacy jQuery core compatibility
//>>description: Support versions of jQuery core lower than 3.5 (down to 1.8)

By the way, this file's role would be much clearer if it was named "legacy-jquery-core.js".

@mgol mgol transferred this issue from jquery/jquery-ui Nov 14, 2023
@mgol mgol transferred this issue from jquery/download.jqueryui.com Nov 14, 2023
@mgol
Copy link
Member

mgol commented Nov 14, 2023

I think the name of the file is fine since it does patch jQuery Core.

Updating the metadata sounds good to me. I think I'd use uppercase "Core". PRs welcome!

@Chealer
Copy link
Author

Chealer commented Nov 14, 2023

Whether the file patches jQuery Core is arguable, but regardless of whether the name is correct or not, it is not good. The file could be named "small-file-which-contains-functions.js", which would be 100% correct, but that would certainly not be a good name, as it describes implementation rather than role. A good name should focus on the component's objective rather than on its internals.

I agree that "Core" should be capitalized.

@mgol
Copy link
Member

mgol commented Nov 14, 2023

It’s not just internals, though. Loading jQuery UI with jQuery 1.8 makes methods .even() & .odd() available, for example. This is observable to users.

@mgol
Copy link
Member

mgol commented Nov 14, 2023

I’m not married to the name, BTW, but this is churn that we even cannot really introduce in a patch release, it’d have to wait for 1.14 if we release one at all. I’m not too keen planning such things, especially that jQuery UI is in maintenance mode and there are many more changes that would be good to do but we will likely never do them.

cc @fnagel for your opinion

@fnagel
Copy link
Member

fnagel commented Nov 14, 2023

@mgol I'm fine with changing label and description in the download builder as @Chealer has a point here, the label is somehow confusing and could be improved.
Changing the file name needs to be done in a minor release which will not likely to be happen anymore. So let's skip this.

Whether the file patches jQuery Core is arguable

@Chealer Why? It patches jQuery, not jQuery UI.

@Chealer
Copy link
Author

Chealer commented Nov 14, 2023

@fnagel Oh sorry, I meant to emphasize patches, not Core. The word "patch" has been largely extrapolated since, but originally, it described tape patches applied over previous tape, therefore replacing previous code. jquery-patch.js does not replace jQuery, it merely extends it.

@Chealer
Copy link
Author

Chealer commented Nov 14, 2023

It’s not just internals, though. Loading jQuery UI with jQuery 1.8 makes methods .even() & .odd() available, for example. This is observable to users.

Right. What I meant by internals was not that it was invisible outside, but that it's an implementation detail. That these are visible not just to jQuery UI is both accidental and undesirable.

@mgol
Copy link
Member

mgol commented May 13, 2024

That these are visible not just to jQuery UI is both accidental and undesirable.

I agree but at this point we'd prefer to avoid introducing breaking changes by removing this module.

@Chealer
Copy link
Author

Chealer commented May 14, 2024

I am fine with that @mgol , I was not saying this should be changed. To clarify what I meant to say:
A good name should focus on the component's objective rather than on its implementation details (whether or not these details are purely internal or visible).

@mgol
Copy link
Member

mgol commented May 14, 2024

The current plan for 1.14 is to keep the file for backwards compatibility but to not depend on it in code. This means the only purpose for it will actually be patching jQuery and not making jQuery UI compatible with older jQuery.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
4 participants
@fnagel @Chealer @mgol and others