Below is a summary of the discussion from this week’s JavaScript chat (agenda, Slack transcript). Notes compiled by @youknowriad.

Participants: @aduth, @atimmer, @bpayton, @gziolo, @jorbin, Jorge Costa, @omarreiss, @welcher, @youknowriad

Documentation

A new post to track the work on the JS Docs effort has been published.

Gutenberg now includes a tool to generate documentation based on JSDoc. It’s being used to document the selectors and actions available in the data module.

Action items to follow-up on:

• Have the Gutenberg docs automatically generated as part of the handbook build (@youknowriad, @pento)
• Adapt WP-Parser to generate documentation for developer site from JSDoc ahead of 5.0 release (@herregroen)
• Get the generated docs into the Gutenberg handbook even if build is not yet automated (@youknowriad)
• To avoid the disparity between the JSDocs initiative and the docs generated in Gutenberg, coordinate with relevant teams as appropriate and try to schedule a joint meeting.
  

Polyfills

We discussed the best way to load JavaScript polyfills in WordPress for WordPress scripts and plugins while avoiding the duplicated code and reduce the bundle size as much as possible. There’s no clear path forward yet. An idea that’s being explored is to use the fact that browsers that support `modules` also support async/await, arrow functions, Set/Map, Promise, generators. This means we can generate two scripts once for browsers supporting “modules” (most recent browsers) and one for browsers that don’t (IE11) (See related blog post explaining the technique).

@bpayton proposed trying an alternative approach to target a base stub script  which includes all polyfills. This will be proposed in a Gutenberg pull request and evaluated next week.

Agendas and meeting nodes

@jorbin raised a concern about the availability of meeting notes and agendas for #core-js meetings. On previous chats, it has been decided to avoid those because of the effort required to prepare and compile those for #core-js chat leads.

To address this, a group to rotate on the responsibility of taking notes has been created: @aduth @atimmer @gziolo @nerrad @omarreiss @youknowriad all volunteered to do so. If you want to volunteer as well, please leave a comment.

Deprecation strategy for WordPress JavaScript code

Two separate issues were raised regarding the deprecation strategy:

Communication around the deprecations

It has been argued that deprecating code in JavaScript is a requirement. Unlike PHP, keeping old APIs forever is not an option because of bundle size and performance.

It has been raised that It’s important for us to keep the trust plugin authors have towards WordPress in maintaining stable APIs without breakage. A clear communication strategy with plugin authors and developers is important in keeping the level of trust developers have towards WordPress APIs.

@atimmer proposed a path towards a clear deprecation strategy

1. Decide that a feature needs to be deleted (because of user reasons).
2. Implement a strategy for users to be able to move to the alternative of the feature to serve the use-case the feature was serving.
3. Deprecate the feature in a way that potential users are given notice that the feature will be removed. Highlight the strategies a user could take that we’ve implemented in step 2.
4. Wait for a specified period.
5. Remove the feature that has been deprecated.

It was argued that communicating the benefits of these deprecation is crucial instead of emphasizing on the potential breakage. We also discussed that raising awareness about this strategy to plugin authors is crucial to the trust factor.

Upgrade existing scripts (packages) without breaking existing versions.

@aduth proposed the introduction of versioned scripts and automatically wrapping scripts in closures to avoid conflicts between two different versions of the same script. (See demonstration)

Discussion on the deprecation strategy will continue in the next meetings.