Add ESM Script Documentation

[marklundin]

This PR updates the documentation with the following

• ESM Script based intro
• Updates Script Attributes docs to reflect new system
• Removes migrations guide from legacy -> scripts 2.0
• Adds migration docs from scripts 2.0 - ESM Scripts
• Move's older scrips 2.0 docs into legacy subfolder

I confirm I have read the contributing guidelines and signed the Contributor License Agreement.

[marklundin]

Thanks for the thorough review on this @willeastcott 🙏

[marklundin]

Added a preview link of this PR here preview.developer.playcanvas.com

[willeastcott]

I think I've come to the realization that making these changes in the GitHub UI is not very efficient! I'll let you take over. 😉

Essentially, it's just a matter of replacing ScriptType with Script and updating ESM code blocks to modern JS (arrow function, no var, etc).

[marklundin]

Updated w/ linting @willeastcott

[willeastcott]

Updated w/ linting @willeastcott

Thanks! I'll do another pass when I get a second...

[marklundin]

@willeastcott this is now updated and ready for review 🙏

[Maksims]

Please use other name than "legacy" as it is used by actual "legacy" system. While non-module current scripting system is still a viable path to go.

[mvaligursky]

Please use other name than "legacy" as it is used by actual "legacy" system. While non-module current scripting system is still a viable path to go.

Totally agreed.

[marklundin]

Willing to consider suggestions if you have any :D

[mvaligursky]

Chat GPT options:

• Classic Script: Emphasizes that it’s a traditional, reliable approach still in use.
• Standard Script: Suggests that it’s the default or commonly used version.
• Legacy Plus: A nod to its legacy roots but indicating that it's still supported and active.
• Vanilla Script: Implies a plain, unenhanced version without modern module systems.
• Core Script: Highlights that it’s the fundamental, core version before the modular approach.
• Traditional JS: Stresses the older, yet still valid, method of scripting.
• Unified Script: Suggests it’s a unified approach, consistent across various use cases.
• Direct JS: Indicates a straightforward, direct way to write and execute scripts.
• Base Script: Implies it’s a base or foundational version of your scripting system.
• Standard JS: Suggests it’s the standard, widely accepted approach.

I like the Classic the most I think.

[Maksims]

There is no common consensus on what non-module scripts are called, but I've seen multiple places call them "classic".

[marklundin]

It needs to communicate that one is a recommended approach. There is no reference to the older scripting system now, so “legacy” does work here, but I see your point. ESM/Classic though is too ambiguous.

On Tue, 3 Sep 2024 at 10:38, mrmaxm @.***> wrote:

There is no common consensus on what non-module scripts are called, but I've seen multiple places call them "classic".

— Reply to this email directly, view it on GitHub https://github.com/playcanvas/developer.playcanvas.com/pull/644#issuecomment-2326063758, or unsubscribe https://github.com/notifications/unsubscribe-auth/AADJFLGNPYNHEQD35CC63ODZUV7RPAVCNFSM6AAAAABFLFV6CGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMRWGA3DGNZVHA . You are receiving this because you authored the thread.Message ID: @.***>

[Maksims]

There is no reference to the older scripting system now, so “legacy” does work here

There is "Legacy Scripting" - has been used around forums, docs, and other places. It also indicates that it is "not to be used", but I would strongly suggest that this should not be the case, as many users still can use current system without any drawbacks. Most people will not migrate to ESM scripts with existing projects due to lack of clear benefits and amount of work it might require.

MDN uses "classic" term for non-module scripts.

[marklundin]

Yep, at least for consistency 'Classic' might be sufficient. My only concern is that we want to push a single route moving forward, and ESM/Classic doesn't necessarily communicate that. Maybe Next/Classic? @willeastcott any thoughts here?

[mvaligursky]

I would go for Classic and Modern perhaps.

[willeastcott]

I'm not a fan of 'Modern'. I like these two options close to equally:

• ES5 scripts vs ESM scripts
• Classic scripts vs ESM scripts

[Maksims]

I'm not a fan of 'Modern'. I like these two options close to equally:

• ES5 scripts vs ESM scripts
• Classic scripts vs ESM scripts

Technically they are not ES5, as you can use classes without ESM.

[willeastcott]

Technically they are not ES5, as you can use classes without ESM.

True.