deprecate polyfill

[ljharb]

Now that the proposal is at stage 3, per previous agreement/intention, the polyfill should be deprecated on npm, and likely the code removed from the repo, so that there's no confusion that TC39 is providing an official polyfill (something we don't do).

[SimenB]

I assume this entails moving it to a different repo and publish under some other name?

[ljharb]

That's up to whoever wants to maintain it. The important part is that it be a distinct package name that has no direct relationship to tc39 (besides, of course, that its maintainers may also be delegates).

I certainly plan to author my own polyfill, as I'm sure do a number of others, and it's important to let the community vote with their feet without a "blessing" from the standards body.

[littledan]

Maybe the polyfill's development could be moved to a different repository outside of the tc39 organization, but I see no reason to change the name on npm (which does not contain the string "tc39", is not in any particular TC39-related organization, etc). Let's just explain clearly that the polyfill is maintained by the champion group, not TC39 (as it has been all along; Stage 3 does not change that) but I haven't seen any evidence that JS developers are confused in this area currently.

Overall, comments from @ljharb on the polyfill throughout its development have been quite hostile towards its developers, and I would like to see this pattern come to an end. I expect that the polyfill which is currently hosted in this repository will continue to be developed somewhere or other. I don't see why it should be considered deprecated. It is not appropriate of @ljharb to assert otherwise; that is up to the authors of the code.

[ljharb]

We explicitly discussed this in plenary.

https://github.com/tc39/notes/blob/827c5f98554b6e04d81c2c265f78f6f7ddf8415a/meetings/2019-12/december-3.md#topic-policy-on-published-codepolyfills-in-proposal-repos:

Temporal polyfill will get archived when the proposal is stabilised.
When a proposal hits Stage 4, ideally all of those repos are archived. It would be problematic if there were a polyfill that still lives in a proposal repo.

The polyfill was developed in this org, its authors do not own it, TC39/Ecma does, and thus it is not, in fact, up to its authors at all - it's up to the committee. If the authors wanted ownership of it, it would have been developed outside of this org in the first place.

The code is of course licensed such that anyone, including the authors, can take the code and publish it separately, but the license doesn't govern the specific package name. In addition, the entire point of TC39 not blessing an implementation would be violated if the name is kept - all current usage/popularity of that package name was under tc39 auspices, and a polyfill should have to start fresh (the current package should not point to any polyfill implementation, in other words).

https://github.com/tc39/notes/blob/827c5f98554b6e04d81c2c265f78f6f7ddf8415a/meetings/2019-12/december-3.md#conclusion-4

TC39 does not maintain official polyfills

[littledan]

Right, we all agree that this repository does not contain an official polyfill. However, its copyright has not been attributed to anyone else; it is just licensed freely like any other open source project. This polyfill is still under development by its authors. I agree that any continued development after Stage 4 will have to take place outside of this repository. That does not add up to depreciation in my mind. The committee did not adopt your proposal to prohibit the development of polyfills in proposal repositories.

[ljharb]

Stage 3, not 4, was the point at which we discussed development ceasing in this repo.

The committee did not adopt my proposal but they did agree that tc39 should not have blessed polyfills.

[littledan]

Yes, ending development after Stage 3 was discussed, but not adopted as a conclusion in the notes. My understanding of TC39's process remains that delegates can make use of their repository as is useful for development, as long as no one claims anything is an "official" TC39 polyfill, just the work of the champion group.

I think it would be best from here if the champions were allowed to land the changes that we agreed on for Stage 3, and then work on productionizing the polyfill can take place in another repo.

I don't see what that has to do with deprecating, and I think it is harmful to inclusion in TC39 for you to act as police enforcing policies that we have not adopted. Filing an issue asking for a codebase to be deprecated is an insult to those who worked hard on that code.

[ljharb]

That was the telegraphed intention by @pipobscure and the reason I assented to stage 3.

What I think is harmful is destroying any delegate's trust in proposal champions by deviating from clearly telegraphed intentions after stage advancement.

You are using very charged language here, attacking my character, and I don't find it appropriate. Please stop.

[littledan]

I think it would be best from here if the champions were allowed to land the changes that we agreed on for Stage 3, and then work on productionizing the polyfill can take place in another repo.

These are the next steps I'm proposing. Don't these match up with what Philipp previously said?

[ljharb]

What happens in another repo is totally fine, and I'm not making any requests about it. The code can be extracted to that other repo at any time, even if it's deleted from this one, since it's in the git history. Whether a few additional Stage 3-related changes land in it in the near future (including publishing those changes) is immaterial to me; i'm not insisting that the instant stage 3 got consensus is some kind of instant "deadline" or anything.

Once the final stage 3 changes are landed, though (and presumably published), which I assume would happen soon, then i'd also assume the following steps to closely follow:

1. delete the polyfill code from this repo, to avoid confusion
2. npm deprecate all existing versions of the tc39-produced polyfill package, to ensure that nobody is depending on it in production
3. (if the champions, or anyone else, so desires) copy the MIT-licensed code to another repo, outside of the tc39 github org, and publish it to npm under a new name.

… all of which are what has been discussed and telegraphed as the intention of the proposal champions since this question first arose.

[justingrant]

My understanding is that the plan of record is this:

1. Users of the current polyfill should be warned loudly and repeatedly not to use it in production. The current docs and README include warnings, Readme & doc changes for Stage 3 #1440 will beef up the docs/README warnings, and Add install-time and runtime warnings (e.g. "not for production use") for polyfill #1447 will (when resolved) add warnings at install time and runtime too.
2. We'll do a "Stage 3 release" of the polyfill that includes fixes and changes we agreed on in last week's plenary meeting.
3. Soon after, champions will start on a production polyfill. This development will happen in a new repo.
4. After there's a production polyfill available (from any source), then retire the current non-prod polyfill. As long as Test262, docs playground, and cookbook docs/tests keep working (they need a polyfill) then I don't have a strong opinion about how this retirement happens. If npm deprecate is the right way to retire, then we'd direct users to any known prod polyfills in the deprecation message, and revise that message if more prod polyfills emerge.
5. The docs should move to MDN at some point, hopefully soon. See What's the plan to get Temporal docs into MDN? #1449.
6. During Stage 3, champions will continue to fix bugs (in spec, docs, polyfill, tests, etc) reported by reviewers or community members. Bug reports are coming in at a relatively rapid pace, but this pace should slow after low-hanging fruit problems are found and fixed and the flurry of activity around Stage 3 advancement dies down. That said, more bug reports will come in after Stage 3 release but before a prod polyfill is available. During that period, champions should make sure that important fixes are applied in both places, but some minor fixes could be deferred to the prod polyfill only.

Anyway, that's my understanding of the current plan. Champions, please correct where I got it wrong!

@ljharb, it sounds like you are also looking for the following:

7. The future production polyfill built by champions should be published to npm under a different name than proposal-temporal.
8. After the Stage 3 polyfill release but before any production polyfills are ready, bugfixes in the current polyfill should be published to npm under a different name than proposal-temporal.
9. After the Stage 3 polyfill release but before any production polyfills are ready, mark the current polyfill as deprecated in npm.
10. After the Stage 3 polyfill release but before any production polyfills are ready, delete the current polyfill code from this repo.

Is that right? If not please correct!

Also, I don't have a lot of context outside this thread but from reading above I'd like to make sure there's clarity about the goals of 7-10, in case we can find easier/better ways to achieve the same goals. Here's my understanding:

• a. Developers shouldn't be using any non-production polyfill in production, because the current polyfill wasn't designed for prod use and breaking prod apps is bad.
• b. Developers shouldn't expect any relationship between TC39 and polyfills, other than helping developers discover polyfills that exist, because we want to encourage the community to build polyfills without TC39 having a thumb on the scale.

Is this an accurate statement of the goals? Did I miss any? Are the "because" explanations correct?

In case it's helpful, here's my understanding of the champions' goals:

• i. Maximize useful community feedback & bug reports during the next few months, so that we can avoid painful changes later and also to ensure that the docs address common pitfalls that early users are running into.
• ii. Reduce work required for champions to manage that feedback during the next few months, because time spent managing feedback will degrade our ability to do actual useful work on the proposal like improving docs or tests.
• iii. Reduce the delay before there's a production polyfill, because a prod polyfill will yield different community feedback than non-prod tire-kickers.
• iv. Same as (a) above - don't use non-prod polyfills in prod!
• v. To support (i) and (iv), it should be easy for developers interested in trying Temporal to find out what polyfill(s) are available
• vi. To support (i), (ii), (iv), and (v), it should be easy for developers using outdated or unmaintained polyfills to find one that's current.
• vii. Don't break Test262, browser-devtools console testing (aka "playground"), and docs cookbook (and cookbook tests) all of which rely on a working polyfill.

There are strong opinions on this thread, so I'd urge everyone to be flexible and see if we can come up with a good-enough solution. 🙏

[pipobscure]

@justingrant not quite.

Here are the things that need to happen in order:

1. Move Polyfill code into a separate repo in another org (not TC39)
2. Release a new version to npm from that location making it clear in all documentation that it is in no way endorsed by TC39.
3. Remove all links to the polyfill from the proposal repository.

All if this should happen soon. Whether we still do the fixes for stage 3 in this repo and then move it is up for debate, but the polyfill needs to now leave this repo soon.

The rationale is that the polyfill here cannot be endorsed or appear to be endorsed by TC39. It would be an unfair advantage that is unjustified. Especially since there are other groups of polyfills out there.

[ljharb]

That all sounds exactly right to me.

The reason I think the current npm name should not be used moving forward is exactly what @pipobscure has stated - that it would be an unfair and unjustified advantage in what is otherwise a free-ish market.

[justingrant]

If there's going to be multiple polyfills then making them all easily and equally discoverable seems like a good thing! A few follow-up questions:

That all sounds exactly right to me.

@ljharb, do you mean you agree with my summary above AND @pipobscure's, or only Philipp's? If the latter, would it be possible to also get your response to #1446 (comment) so we are sure that we understand your POV? Thx!

1. Move Polyfill code into a separate repo in another org (not TC39)

@ljharb other than the polyfill, do you have a strong opinion that other things should be removed too? Conversely, are there things that you have a strong opinion should NOT be moved out? Here's a list of what's currently in the repo now.

• Documentation
• Docs playground: enables running Temporal code live in the browser devtools console (from any docs page) or in a Node REPL via npm run playground. This capability is very valuable for repro-ing bugs, for users trying out Temporal easily, etc. Requires an implementation, which for the next few months means a polyfill.
• Docs cookbook. Use-case-specific code samples with accompanying documentation. These samples also run as part of npm test of the polyfill. Requires an implementation.
• Test262 tests. Requires an implementation.
• Non-Test262 tests. Requires an implementation.
• Champions' meeting notes.
• Open GH issues related to the polyfill and anything else we decide to move into the new repo

Finally, if any of the "requires an implementation" items above should be retained in this repo, then does anyone object if the champions just do the easiest thing which is to add a dependency to the current polyfill in its new repo and update that dependency once there's a production polyfill available?

3. Remove all links to the polyfill from the proposal repository.

I assumed that it was desired to help developers find implementations of a proposal. Like these finished proposals do:

• https://github.com/tc39/proposal-string-matchall#polyfillshim
• https://github.com/tc39/proposal-promise-any#implementations
• https://github.com/tc39/proposal-string-replaceall#implementations
• https://github.com/tc39/proposal-well-formed-stringify#implementations
• https://github.com/tc39/proposal-json-superset#implementations
• https://github.com/tc39/proposal-async-iteration#implementation-status
• https://github.com/tc39/proposal-numeric-separator#implementations
• https://github.com/tc39/proposal-string-left-right-trim#implementations
• https://github.com/tc39/proposal-regexp-unicode-property-escapes#implementations
• https://github.com/tc39/proposal-object-rest-spread#transpilers
• https://github.com/tc39/proposal-regexp-named-groups#implementations
• https://github.com/tc39/proposal-regexp-dotall-flag#implementations

I assume that this convention should be retained in the Temporal repo too, which means that we'd link to the existing polyfill and add more links as more polyfills and native implementations come online. If you disagree, why?

[ljharb]

@justingrant the playground seems fine to keep (altho presumably the extracted polyfill would want its own); when there’s more polyfills available, it could always be expanded to support multiple ones. The docs of course i assume would stay (but that is entirely up to y’all), along with the cookbook and test262 stuff.

It doesn’t make sense to me to keep polyfill-related issues after the polyfill code is gone, is there a reason to keep it?

Proposals definitely often link to polyfills - any spec-compliant ones, no preference shown. That would include one based on the code extracted from this repo. There’s a huge difference between linking to an unaffiliated repo and hosting the code from an affiliated one :-)

[justingrant]

the playground seems fine to keep (altho presumably the extracted polyfill would want its own); when there’s more polyfills available, it could always be expanded to support multiple ones. The docs of course i assume would stay (but that is entirely up to y’all), along with the cookbook and test262 stuff.

OK, cool, glad you're flexible on this. Champions will discuss and come up with a plan quickly. The plan could be anything from "only move the polyfill" to "move everything except spec and readme", depending on what's the best way to minimize throwaway work from the repro split (esp. given that the plan is the move the docs to MDN relatively soon) while not interfering with getting feedback from early adopters.

Proposals definitely often link to polyfills - any spec-compliant ones, no preference shown.

Great. We'll do this. We'll also plan to link to other polyfills (also with no preference shown) in the warning messages for the current polyfill to help users navigate the name change. When new polyfills arrive, we'll happily update the warning messages. Keep in mind there's no particular affection among the champions for our own polyfill-- we want users to easily be able to find an implementation, but none of us particularly care which implementation(s) are used as long as they're easy to discover. Until yesterday I had no idea that polyfill competition was a thing! ;-)

It doesn’t make sense to me to keep polyfill-related issues after the polyfill code is gone, is there a reason to keep it?

None that I know of.

[MaximSagan]

Seems like there hasn't been any movement on this for a couple months. Is this polfyfill still the go-to polyfill for Temporal? (Google seems to think so.)

[ljharb]

Indeed; the polyfill remains undeprecated, despite March being the time to do it - and I also haven't seen any production-ready polyfills available yet. (I suspect that deprecating this one would accelerate the timeline of the ecosystem creating them - i know that i won't start making one until then)

[ptomato]

Seems like there hasn't been any movement on this for a couple months. Is this polfyfill still the go-to polyfill for Temporal? (Google seems to think so.)

@MaximSagan I'm not sure what your expectation of "go-to" is; this polyfill is not intended for production use, as the note in the README says. We have just a few days ago finished incorporating some changes to the proposal from last week's TC39 meeting. We intend to make one last release of the package on NPM so that people who do use it are not using a nonconformant version of Temporal (as far as we know) while they wait for other polyfills, and then deprecate the NPM package. We're working on writing the messaging around this process.

[justingrant]

Following up: the original temporal polyfill is now deprecated. Specifically:

• There's a new repo (https://github.com/js-temporal/temporal-polyfill) where a fork of the old polyfill will live. Folks will be working on improving it. Contributors welcome!

• This repo's readmes (both the root readme and the /polyfill readme) have been edited to reflect the current state of the old polyfill and to forcefully encourage existing polyfill users to migrate to one of the available polyfills that exist. Currently there's only one listed (@js-temporal/polyfill from the repo above) but the readme encourages any polyfill developers to add theirs to the list.

• We just published the final 0.9.0 release of this repo's polyfill to NPM. This new release includes a runtime warning to this repo's polyfill to encourage users to migrate to another polyfill.

• This repo's polyfill is deprecated in NPM

• The old polyfill code continues to exist in this repo for the purpose of running tests and to power the documentation playground (which allows viewers of the docs to experiment by running Temporal code in the browser devtools console). A few related notes:
  • The importable entry point (index.js) has been removed, along with the build steps for building importable output bundles. These are not needed anymore because now the only use of the polyfill is to run tests and support the docs playground.
  • On a case-by-case basis, we may port some changes from @js-temporal/polyfill or other polyfills into this repo if we believe that those PRs will improve the speed and/or accuracy of tests. With more than 2700 Test262 tests already (with many more being built) improving test performance is important for the productivity and sanity of anyone working on this proposal. One thing we will NOT do is to make code changes in this repo that will cause significant divergence from the structure of the spec and/or the current polyfill, because that would make it harder for implementers. This means that the only changes we should expect to see here in this repo are minor, scoped, mostly-perf-focused changes like Speed up non-ISO calendar tests about 10x by caching DateTimeFormat instances #1624.

I'm going to close this issue now, but feel free to follow up with any questions or concerns.

[ljharb]

Thanks! I know this was a large effort, and it’s appreciated.