[Polyfill] Usage and Install recommendations

[romulocintra]

The actual readme recommends to import the polyfill as a Module.

import { Temporal } from 'proposal-temporal/lib/index.mjs';

IMHO, documentation should be more specific and explore different ways of using the polyfill :

This polyfill is intended to be used as a library without global namespace pollution, or can I use it globally as a script tag with umd version?

My feedback is that different strategies must be explained independent of having a recommendation, also should include different scenarios, patterns or use cases, having in mind a future "migration" path for the time that Temporal is shipped to the browsers.

Personally one of the biggest advantages of Temporal is being a proposal with a polyfill, but if I use it as recommended, it may include a future build step, when migrating to the final API that is likely to be on the global namespace.

In my personal use case, I would go for the umd version and treat Temporal the same as I do with other polyfills, load through a service doing feature-detection then loading as it is needed. IMHO is the clean migration path for those that already supporting browsers >=IE11.

[littledan]

Thanks for filing this issue, @romulocintra . I want to recommend that we treat Temporal just as a module, and not as a polyfill, until Stage 3. Or maybe even until a little bit later: after it ships in a browser, we'll have a real guarantee of stability. After some "tipping point", the API will be stable, and we can have some confidence that it will ship everywhere more or less as is, and be compatible. I agree that, longer term, conditional polyfilling techniques are useful. But I think it's too soon for them right now.

If we encourage people to use these techniques now, it risks preventing us from being able to evolve the API. For example, say we rename plus to add, but lots of code on the Web already has the logic of if (typeof Temporal === "undefined") { globalThis.Temporal = /* ... */ }. In this case, code using the plus method would break as soon as Temporal is added to the global object by default. This could make shipping Temporal break the web, since it would cause the polyfill paths to not be taken!

These aren't my ideas; they come from the W3C TAG polyfill guide. I find their arguments persuasive, but maybe people here have other thoughts about this topic, or how to apply these concepts in this case.

[ptomato]

I think the documentation is already clear on this, but what I've done is to make sure Temporal is not copied onto the global object when the library is imported via require() or import.