Javascript Chat Summary – August 7

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

Have a topic for discussion for the next meeting? Leave a suggested edit on next week’s agenda.

Automating Publishing to npm

Slack Conversation

Problem: Publishing modules to npm can be difficult because it is not always clear at the time of publishing to what version the package should be updated. The individual performing the publish is not always the same as the contributors who had proposed changes to the package.

Options:

  • Adopt conventional commits to enable automatic versioning (pull request)
    • Issue: This is hard to enforce
  • Encourage developers to introduce relevant changelog entries as part of proposed changes. The type of change should indicate versioning requirements.
    • Issue: Not every version bump is caused by directly by new changes, sometimes indirectly by updated dependencies.
    • Issue: Prone to frequent merge conflicts with many developers adding entries to the same text file.

Decision: Encourage developers to introduce changelog entries and evaluate success in a future meeting.

Package Deprecations Versioning

Slack Conversation

Problem: When deprecating a feature in Gutenberg, we add logging to highlight the deprecation, and allow for two minor releases of the plugin before removing the functionality. With this in mind, how do we handle versioning of modules? Following SemVer, the major version should be bumped on backwards-incompatible changes. If the deprecation is not entirely faithful and therefore introduces a breaking change, it results in the need for two separate major version bumps by the removal of a single feature.

Discussion points:

  • Is this really a common use case?
  • Could it be considered a good thing to promote the idea that deprecation “shims” should be fully compatible?
  • How does SemVer consider deprecations?
    • Very specifically: “Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated.”

Decision: The major version should be bumped on any backwards-incompatible change. This will usually occur at the final removal of the feature. The deprecation should be fully backwards-compatible and, if it is not, it should warrant a separate major version bump.

Packages

URL

Slack Conversation

Problem: There are several inconsistencies between the WordPress PHP implementation of add_query_arg and the parallel addQueryArgs from the @wordpress/url package:

Name pluralization: addQueryArgs (JS) vs. add_query_arg (PHP)
Arguments: url, param (JS) vs. param, url (PHP)
Usage: Object only (JS) vs. object or key+value pair (PHP)

Discussion points:

  • Consistency vs. improvements
  • Real-world workflows where developers will expect JavaScript reimplementations to behave the same as their PHP counterpart.
  • In general, we should seek to avoid confusion in appearing similar if in-fact the behaviors are not the same.

Decision: There will be no changes to the name or argument order of the addQueryArgs function. Supporting key and value arguments may be a separate enhancement to consider.

Data Plugins API

Slack Conversation

Announcement: The @wordpress/data module now supports a plugin API. Persistence behaviors, which were previously baked in, are now extracted out to an opt-in plugin. This should help improve isolation of specific behaviors, and allow external consumers to use only specific features relevant for their products.

A new pattern for asynchronous state behaviors has been implemented, distributed as the @wordpress/redux-routine package and integrated with the @wordpress/data module via a new controls plugin.

DOM Ready

Slack Conversation

Announcement: A fix has been backported from the Meta team into the @wordpress/dom-ready package, addressing an issue where callbacks may not be called reliably if the document was in specific states. This was the cause of intermittent white-screen issues on the Gutenberg marketing page.

Open Floor

Usage of wp.api

Slack Conversation

Question: Do we still use wp.api ?

Answer: Only in the (now-deprecated) withAPIData higher-order component. Once this deprecation is complete, there will be no more usage of wp.api and it can be safely removed.