deprecation(path): split off all constants into their own files and deprecate old names

[lino-levan]

Closes #4070.

[iuioiua]

LGTM! However, I wonder whether it might be worth having a constants.ts instead. That'd be 3 fewer files, and next-to-no added dependency cost. Doing so would require deprecating separator.ts files. WDYT, @lino-levan and @kt3k?

[lino-levan]

I'm neutral on this. I'm curious to hear what @kt3k thinks.

[kt3k]

However, I wonder whether it might be worth having a constants.ts instead. That'd be 3 fewer files, and next-to-no added dependency cost. Doing so would require deprecating separator.ts files.

constants.ts sounds good to me.

[iuioiua]

@lino-levan, are you able to reorient this PR to instead introduce constants.ts files?

[lino-levan]

Yup, let me do that right now.

[kt3k]

I don't think the IDE (deno lsp) can render $STD_VERSION part as the corresponding version number, and this url notation can be confusing. How about just omitting the urls in deprecation notes?

[iuioiua]

Including URLs is fine if the @$STD_VERSION portion is omitted. The documentation should be rendered fine if we also wrap the URL in a {@link <url>} tag. E.g. the win32 export in path/mod.ts renders correctly.

[iuioiua]

I've made some tweaks, Lino. Please tell me what you think.

1. Changed the constant names to be uppercase. This is a common convention. I think it's fine to also do this in path/constants.ts, even though it's evaluated based on the current platform, as it never changes after this evaluation.
2. Aligned JSDocs of the deprecated constants with others in the codebase, using @linkcode and @link tags.
3. Brought the removal version forward to 0.216.0, as this should be an easy change in user code (debatable).

The one thing remaining is moving any internal use of the deprecated constants to the new ones. Are you able to do this?

[lino-levan]

Changed the constant names to be uppercase. This is a common convention. I think it's fine to also do this in path/constants.ts, even though it's evaluated based on the current platform, as it never changes after this evaluation.

Had no strong feelings either way. Didn't want to bikeshed on it so just picked one idea and ran with it. SGTM.

Aligned JSDocs of the deprecated constants with others in the codebase, using @linkcode and @link tags.

I really need to learn how those work. Thanks!

Brought the removal version forward to 0.216.0, as this should be an easy change in user code (debatable).

Picked 1.0.0 for same (lack of) reason as number 1. SGTM, thanks.

The one thing remaining is moving any internal use of the deprecated constants to the new ones. Are you able to do this?

Busy tonight, I mentally made a note to do it, but then I forgot to. Will get to it tomorrow if you don't want to do it right now.

[iuioiua]

Busy tonight, I mentally made a note to do it, but then I forgot to. Will get to it tomorrow if you don't want to do it right now.

No rush for now 🙂

[iuioiua]

I've made a couple of tweaks and fixes. Now, LGTM! I'll let Yoshiya do the final review.

[iuioiua]

Sidenote: I see no use case for this sep argument. Ditto for the Windows version. Perhaps, it should be deprecated in another separate PR.

[lino-levan]

Probably work for another PR, but this makes sense 👍

[kt3k]

LGTM. Nice work!