JS docs initiative: Add inline-docs for JavaScript! (part 2)

Because of a restriction of wordpress.org, you cannot comment on posts older than 120 days. This new post can be used to track the work on Javascript inline-docs. The original post on the JS docs initiative can be found here. In this post I have excluded files that have already been completed.

At the bottom is a list of every first-party JavaScript file in core. Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute

  1. Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
  2. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  3. Update your local WordPress SVN (use svn up) or Git repo (use git pull) to the latest version of WordPress trunk.
  4. Create a new ticket on Trac for the file.
    • Format the title as “JSDoc: path/to/file.js”.
    • The Type should be “defect (bug)”.
    • Assign the ticket to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs and javascript focuses.
  5. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.
  6. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

We’d like to welcome everyone to start contributing inline documentation! You can start contributing by picking a file from the list of unclaimed files below and claiming it in the comments. Please also see the JS docs handbook page for a step by step guide on how to get started.

Note: Note: To give everyone a chance to claim a file and to ensure the work proceeds as quickly as possible, please only work on one file at a time.

Determining the since version

We use JSDoc’s @since tag to indicate when a particular function was added to WordPress core. When you are documenting a function, you will also need to identify when that function was first introduced.

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

If you use the git repository of WordPress you can also use git to determine the @since version. Either use git blame or the GitHub blame function. Once you have the commit hash which introduced a piece of code you can find out the version by using git tag --contains [commit-hash]. This will list all versions a certain commit has been shipped in. The lowest version is then what you put after the @since annotation.

Note: Make sure that the commit you found it the actual commit where a piece of code was introduced. JavaScript files have been moved around a lot in the past, so make sure to take that into account.

Note: All @since tags should follow the three digit x.x.x format.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly devchat. That’s either #core-js or #core.

Files needing patches:

Checked files are completed, marked files are claimed

  • src/js/_enqueues/wp/customize/controls.js (@jjcomack)
  • src/js/_enqueues/wp/customize/nav-menus.js
  • src/js/_enqueues/wp/customize/widgets.js
  • src/js/_enqueues/lib/gallery.js (@hunkriyaz)
  • src/js/_enqueues/admin/link.js (@andg)
  • src/js/_enqueues/lib/nav-menu.js
  • src/js/_enqueues/admin/plugin-install.js
  • src/js/_enqueues/wp/revisions.js
  • src/js/_enqueues/admin/set-post-thumbnail.js
  • src/js/_enqueues/wp/svg-painter.js
  • src/js/_enqueues/wp/theme.js
  • src/js/_enqueues/wp/updates.js
  • src/js/_enqueues/admin/user-profile.js
  • src/js/_enqueues/admin/widgets.js
  • src/js/_enqueues/deprecated/fullscreen-stub.js
  • src/js/_enqueues/wp/customize/base.js
  • src/js/_enqueues/wp/customize/loader.js
  • src/js/_enqueues/wp/customize/models.js
  • src/js/_enqueues/wp/customize/preview-nav-menus.js
  • src/js/_enqueues/wp/customize/preview.js
  • src/js/_enqueues/wp/customize/selective-refresh.js
  • src/js/_enqueues/wp/customize/views.js
  • src/js/_enqueues/wp/mce-view.js
  • src/js/_enqueues/wp/media/audiovideo.js
  • src/js/_enqueues/wp/media/editor.js
  • src/js/_enqueues/wp/media/grid.js
  • src/js/_enqueues/wp/media/models.js
  • src/js/_enqueues/wp/media/views.js
  • src/js/media/controllers/audio-details.js
  • src/js/media/controllers/collection-add.js
  • src/js/media/controllers/collection-edit.js
  • src/js/media/controllers/edit-attachment-metadata.js
  • src/js/media/controllers/embed.js
  • src/js/media/controllers/featured-image.js
  • src/js/media/controllers/image-details.js
  • src/js/media/controllers/library.js
  • src/js/media/controllers/media-library.js
  • src/js/media/controllers/region.js
  • src/js/media/controllers/replace-image.js
  • src/js/media/controllers/site-icon-cropper.js
  • src/js/media/controllers/state-machine.js
  • src/js/media/controllers/state.js
  • src/js/media/controllers/video-details.js
  • src/js/media/models/attachment.js
  • src/js/media/models/post-image.js
  • src/js/media/models/post-media.js
  • src/js/media/models/query.js
  • src/js/media/models/selection.js
  • src/js/media/routers/manage.js
  • src/js/media/utils/selection-sync.js
  • src/js/media/views/attachment-compat.js
  • src/js/media/views/attachment-filters.js
  • src/js/media/views/attachment-filters/all.js
  • src/js/media/views/attachment-filters/date.js
  • src/js/media/views/attachment-filters/uploaded.js
  • src/js/media/views/attachment.js
  • src/js/media/views/attachment/details-two-column.js
  • src/js/media/views/attachment/details.js (@maartenleenders)
  • src/js/media/views/attachment/edit-library.js
  • src/js/media/views/attachment/edit-selection.js
  • src/js/media/views/attachment/library.js
  • src/js/media/views/attachment/selection.js
  • src/js/media/views/attachments/browser.js
  • src/js/media/views/attachments/selection.js
  • src/js/media/views/audio-details.js
  • src/js/media/views/button-group.js
  • src/js/media/views/button.js
  • src/js/media/views/button/delete-selected-permanently.js
  • src/js/media/views/button/delete-selected.js
  • src/js/media/views/button/select-mode-toggle.js
  • src/js/media/views/cropper.js (@kapteinbluf)
  • src/js/media/views/edit-image-details.js
  • src/js/media/views/edit-image.js
  • src/js/media/views/embed.js
  • src/js/media/views/embed/image.js
  • src/js/media/views/embed/link.js
  • src/js/media/views/embed/url.js
  • src/js/media/views/focus-manager.js
  • src/js/media/views/frame.js
  • src/js/media/views/frame/audio-details.js
  • src/js/media/views/frame/edit-attachments.js
  • src/js/media/views/frame/image-details.js
  • src/js/media/views/frame/manage.js
  • src/js/media/views/frame/media-details.js
  • src/js/media/views/frame/post.js
  • src/js/media/views/frame/select.js
  • src/js/media/views/frame/video-details.js
  • src/js/media/views/iframe.js
  • src/js/media/views/image-details.js
  • src/js/media/views/label.js
  • src/js/media/views/media-details.js
  • src/js/media/views/media-frame.js
  • src/js/media/views/menu-item.js
  • src/js/media/views/menu.js
  • src/js/media/views/modal.js
  • src/js/media/views/priority-list.js
  • src/js/media/views/router-item.js
  • src/js/media/views/router.js
  • src/js/media/views/search.js
  • src/js/media/views/selection.js
  • src/js/media/views/settings.js
  • src/js/media/views/settings/attachment-display.js
  • src/js/media/views/settings/gallery.js
  • src/js/media/views/settings/playlist.js
  • src/js/media/views/sidebar.js
  • src/js/media/views/site-icon-cropper.js
  • src/js/media/views/site-icon-preview.js
  • src/js/media/views/toolbar.js
  • src/js/media/views/toolbar/embed.js
  • src/js/media/views/toolbar/select.js
  • src/js/media/views/uploader/editor.js
  • src/js/media/views/uploader/inline.js
  • src/js/media/views/uploader/status-error.js
  • src/js/media/views/uploader/status.js
  • src/js/media/views/uploader/window.js
  • src/js/media/views/video-details.js
  • src/js/media/views/view.js
  • src/js/_enqueues/lib/quicktags.js
  • src/js/_enqueues/wp/shortcode.js (@hanopcan)
  • src/js/_enqueues/lib/cookies.js
  • src/js/_enqueues/wp/a11y.js
  • src/js/_enqueues/lib/ajax-response.js
  • src/js/_enqueues/wp/api.js
  • src/js/_enqueues/lib/auth-check.js (@pskli)
  • src/js/_enqueues/wp/custom-header.js
  • src/js/_enqueues/lib/embed-template.js
  • src/js/_enqueues/wp/embed.js
  • src/js/_enqueues/wp/emoji.js (@igorsch, @nicollle)
  • src/js/_enqueues/lib/list-revisions.js
  • src/js/_enqueues/lib/lists.js
  • src/js/_enqueues/lib/pointer.js (@maartenleenders)
  • src/js/_enqueues/wp/util.js
  • src/js/_enqueues/lib/link.js

Current status:

Happy documenting!

#inline-docs

#javascript

JS docs initiative: Add inline-docs for JavaScript!

There is a new post which you can comment on to claim files.

We are pleased to announce the JS docs initiative! It’s an ongoing effort to get all JavaScript files in WordPress well-documented and make this documentation easily accessible. JavaScript development within WordPress core is speeding up fast, and better documentation will help this work progress as smoothly as possible.

In the last few months, we’ve fixed the JavaScript documentation standards by discussing sticking points in the #core-js weekly meeting. The structural documentation of all the Backbone classes has also been fixed (major props to @herregroen for fixing this).

At the bottom is a list of every first-party JavaScript file in core. Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute

  1. Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
  2. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  3. Update your local WordPress SVN (use svn up) or Git repo (use git pull) to the latest version of WordPress trunk.
  4. Create a new ticket on Trac for the file.
    • Format the title as “JSDoc: path/to/file.js”.
    • The Type should be “defect (bug)”.
    • Assign the ticket to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs and javascript focuses.
  5. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.
  6. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

We’d like to welcome everyone to start contributing inline documentation! You can start contributing by picking a file from the list of unclaimed files below and claiming it in the comments. Please also see the JS docs handbook page for a step by step guide on how to get started.

Note: Note: To give everyone a chance to claim a file and to ensure the work proceeds as quickly as possible, please only work on one file at a time.

Determining the since version

We use JSDoc’s @since tag to indicate when a particular function was added to WordPress core. When you are documenting a function, you will also need to identify when that function was first introduced.

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

If you use the git repository of WordPress you can also use git to determine the @since version. Either use git blame or the GitHub blame function. Once you have the commit hash which introduced a piece of code you can find out the version by using git tag --contains [commit-hash]. This will list all versions a certain commit has been shipped in. The lowest version is then what you put after the @since annotation.

Note: Make sure that the commit you found it the actual commit where a piece of code was introduced. JavaScript files have been moved around a lot in the past, so make sure to take that into account.

Note: All @since tags should follow the three digit x.x.x format.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly devchat. That’s either #core-js or #core.

Files needing patches:

Checked files are completed, marked files are claimed

  • wp-admin/js/accordion.js
  • wp-admin/js/bookmarklet.js
  • wp-admin/js/color-picker.js
  • wp-admin/js/comment.js
  • wp-admin/js/common.js
  • wp-admin/js/custom-background.js
  • wp-admin/js/custom-header.js
  • wp-admin/js/customize-controls.js (@jjcomack)
  • wp-admin/js/customize-nav-menus.js
  • wp-admin/js/customize-widgets.js
  • wp-admin/js/edit-comments.js (@atimmer)
  • wp-admin/js/editor-expand.js
  • wp-admin/js/editor.js
  • wp-admin/js/gallery.js (@hunkriyaz)
  • wp-admin/js/image-edit.js
  • wp-admin/js/inline-edit-post.js
  • wp-admin/js/inline-edit-tax.js
  • wp-admin/js/language-chooser.js
  • wp-admin/js/link.js
  • wp-admin/js/media-gallery.js
  • wp-admin/js/media-upload.js
  • wp-admin/js/media.js
  • wp-admin/js/nav-menu.js
  • wp-admin/js/password-strength-meter.js
  • wp-admin/js/plugin-install.js
  • wp-admin/js/post.js
  • wp-admin/js/postbox.js
  • wp-admin/js/press-this.js
  • wp-admin/js/revisions.js
  • wp-admin/js/set-post-thumbnail.js
  • wp-admin/js/svg-painter.js
  • wp-admin/js/tags-box.js (@carolinegeven)
  • wp-admin/js/tags.js
  • wp-admin/js/theme.js
  • wp-admin/js/updates.js
  • wp-admin/js/user-profile.js
  • wp-admin/js/user-suggest.js (@timhavinga)
  • wp-admin/js/widgets.js
  • wp-admin/js/word-count.js
  • wp-admin/js/wp-fullscreen-stub.js
  • wp-admin/js/xfn.js (@kapteinbluf)
  • wp-includes/js/admin-bar.js
  • wp-includes/js/autosave.js
  • wp-includes/js/comment-reply.js
  • wp-includes/js/customize-base.js
  • wp-includes/js/customize-loader.js
  • wp-includes/js/customize-models.js
  • wp-includes/js/customize-preview-nav-menus.js
  • wp-includes/js/customize-preview-widgets.js
  • wp-includes/js/customize-preview.js
  • wp-includes/js/customize-selective-refresh.js
  • wp-includes/js/customize-views.js
  • wp-includes/js/dashboard.js
  • wp-includes/js/heartbeat.js
  • wp-includes/js/mce-view.js
  • wp-includes/js/media-audiovideo.js
  • wp-includes/js/media-editor.js
  • wp-includes/js/media-grid.js
  • wp-includes/js/media-models.js
  • wp-includes/js/media-views.js
  • wp-includes/js/media/audiovideo.manifest.js
  • wp-includes/js/media/controllers/audio-details.js
  • wp-includes/js/media/controllers/collection-add.js
  • wp-includes/js/media/controllers/collection-edit.js
  • wp-includes/js/media/controllers/cropper.js
  • wp-includes/js/media/controllers/customize-image-cropper.js
  • wp-includes/js/media/controllers/edit-attachment-metadata.js
  • wp-includes/js/media/controllers/edit-image.js
  • wp-includes/js/media/controllers/embed.js
  • wp-includes/js/media/controllers/featured-image.js
  • wp-includes/js/media/controllers/gallery-add.js (@atimmer)
  • wp-includes/js/media/controllers/gallery-edit.js (@manuelaugustin)
  • wp-includes/js/media/controllers/image-details.js
  • wp-includes/js/media/controllers/library.js
  • wp-includes/js/media/controllers/media-library.js
  • wp-includes/js/media/controllers/region.js
  • wp-includes/js/media/controllers/replace-image.js
  • wp-includes/js/media/controllers/site-icon-cropper.js
  • wp-includes/js/media/controllers/state-machine.js
  • wp-includes/js/media/controllers/state.js
  • wp-includes/js/media/controllers/video-details.js
  • wp-includes/js/media/grid.manifest.js
  • wp-includes/js/media/models.manifest.js
  • wp-includes/js/media/models/attachment.js
  • wp-includes/js/media/models/post-image.js
  • wp-includes/js/media/models/post-media.js
  • wp-includes/js/media/models/query.js
  • wp-includes/js/media/models/selection.js
  • wp-includes/js/media/routers/manage.js
  • wp-includes/js/media/utils/selection-sync.js
  • wp-includes/js/media/views.manifest.js
  • wp-includes/js/media/views/attachment-compat.js
  • wp-includes/js/media/views/attachment-filters.js
  • wp-includes/js/media/views/attachment-filters/all.js
  • wp-includes/js/media/views/attachment-filters/date.js
  • wp-includes/js/media/views/attachment-filters/uploaded.js
  • wp-includes/js/media/views/attachment.js
  • wp-includes/js/media/views/attachment/details-two-column.js
  • wp-includes/js/media/views/attachment/details.js (@maartenleenders)
  • wp-includes/js/media/views/attachment/edit-library.js
  • wp-includes/js/media/views/attachment/edit-selection.js
  • wp-includes/js/media/views/attachment/library.js
  • wp-includes/js/media/views/attachment/selection.js
  • wp-includes/js/media/views/attachments.js
  • wp-includes/js/media/views/attachments/browser.js
  • wp-includes/js/media/views/attachments/selection.js
  • wp-includes/js/media/views/audio-details.js
  • wp-includes/js/media/views/button-group.js
  • wp-includes/js/media/views/button.js
  • wp-includes/js/media/views/button/delete-selected-permanently.js
  • wp-includes/js/media/views/button/delete-selected.js
  • wp-includes/js/media/views/button/select-mode-toggle.js
  • wp-includes/js/media/views/cropper.js (@kapteinbluf)
  • wp-includes/js/media/views/edit-image-details.js
  • wp-includes/js/media/views/edit-image.js
  • wp-includes/js/media/views/embed.js
  • wp-includes/js/media/views/embed/image.js
  • wp-includes/js/media/views/embed/link.js
  • wp-includes/js/media/views/embed/url.js
  • wp-includes/js/media/views/focus-manager.js
  • wp-includes/js/media/views/frame.js
  • wp-includes/js/media/views/frame/audio-details.js
  • wp-includes/js/media/views/frame/edit-attachments.js
  • wp-includes/js/media/views/frame/image-details.js
  • wp-includes/js/media/views/frame/manage.js
  • wp-includes/js/media/views/frame/media-details.js
  • wp-includes/js/media/views/frame/post.js
  • wp-includes/js/media/views/frame/select.js
  • wp-includes/js/media/views/frame/video-details.js
  • wp-includes/js/media/views/iframe.js
  • wp-includes/js/media/views/image-details.js
  • wp-includes/js/media/views/label.js
  • wp-includes/js/media/views/media-details.js
  • wp-includes/js/media/views/media-frame.js
  • wp-includes/js/media/views/menu-item.js
  • wp-includes/js/media/views/menu.js
  • wp-includes/js/media/views/modal.js
  • wp-includes/js/media/views/priority-list.js
  • wp-includes/js/media/views/router-item.js
  • wp-includes/js/media/views/router.js
  • wp-includes/js/media/views/search.js
  • wp-includes/js/media/views/selection.js
  • wp-includes/js/media/views/settings.js
  • wp-includes/js/media/views/settings/attachment-display.js
  • wp-includes/js/media/views/settings/gallery.js
  • wp-includes/js/media/views/settings/playlist.js
  • wp-includes/js/media/views/sidebar.js
  • wp-includes/js/media/views/site-icon-cropper.js
  • wp-includes/js/media/views/site-icon-preview.js
  • wp-includes/js/media/views/spinner.js (@avillegasn)
  • wp-includes/js/media/views/toolbar.js
  • wp-includes/js/media/views/toolbar/embed.js
  • wp-includes/js/media/views/toolbar/select.js
  • wp-includes/js/media/views/uploader/editor.js
  • wp-includes/js/media/views/uploader/inline.js
  • wp-includes/js/media/views/uploader/status-error.js
  • wp-includes/js/media/views/uploader/status.js
  • wp-includes/js/media/views/uploader/window.js
  • wp-includes/js/media/views/video-details.js
  • wp-includes/js/media/views/view.js
  • wp-includes/js/quicktags.js
  • wp-includes/js/shortcode.js
  • wp-includes/js/tw-sack.js
  • wp-includes/js/utils.js
  • wp-includes/js/wp-a11y.js
  • wp-includes/js/wp-ajax-response.js
  • wp-includes/js/wp-api.js
  • wp-includes/js/wp-auth-check.js
  • wp-includes/js/wp-backbone.js
  • wp-includes/js/wp-custom-header.js
  • wp-includes/js/wp-embed-template.js
  • wp-includes/js/wp-embed.js
  • wp-includes/js/wp-emoji-loader.js (@dfangstrom)
  • wp-includes/js/wp-emoji.js (@igorsch, @nicollle)
  • wp-includes/js/wp-list-revisions.js
  • wp-includes/js/wp-lists.js
  • wp-includes/js/wp-pointer.js (@maartenleenders)
  • wp-includes/js/wp-util.js
  • wp-includes/js/wpdialog.js (@lisannekluitmans)
  • wp-includes/js/wplink.js
  • wp-includes/js/zxcvbn-async.js (@lisannekluitmans)

Current status:

Happy documenting!

#inline-docs

#javascript

JavaScript Chat Canceled for December 5th

Due to conflicting travel arrangements of some participants following this past weekend’s WordCamp US, we will be canceling the JavaScript Chat for this week. The next meeting will resume as regularly scheduled on Tuesday, December 12, 2017 at 14:00 UTC.

#javascript

Core JavaScript Meeting Time Change

In response to feedback collected during and after last week’s JavaScript chat, the scheduled time of these meetings has been changed to occur one hour later, starting tomorrow at Tuesday, November 14, 2017 at 14:00 UTC and at the same time each Tuesday thereafter.

A few respondents had indicated preference for an Asia/Pacific-friendly meeting time. If enough interest can be generated, a separate meeting may be justifiable. Please indicate in the comments below if you would have interest in regularly attending at a time convenient for this region.

#javascript

JavaScript chat summary for Sept. 26th

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

This week’s meeting was focused around the role of a JavaScript framework in WordPress. The meeting was attended by many guests to the conversation, speaking on behalf of their respective frameworks or web standards:

Google (Web Components / Chrome / Polymer / AMP) – Justin Fagnani (Chrome / Polymer), Alex Russell (Chrome), Wendy Ginsberg (Polymer), Paul Bakaus (AMP), Alberto Medina (AMP)
Facebook (React) – Sophie Alpert, Dan Abramov, Dominic Gannaway
Vue – Evan You

 

What role should a framework play in a WordPress developer’s workflow, and in which contexts? For what purposes do we rely on a framework?

@youknowriad started off the discussion by offering three things as important for the role of the framework

  • Build UI and handle dom updates
  • Build reusable “components”. Reused in Core and potentially for plugins
  • Ability to extend the UI (using the same framework or not)

@dmsnell added it should provide a well-defined interface for isolated components to interact with so that people can have the freedom to build pieces how they want.
@mrahmadawais added that A framework should have a great development community, great documentation
@herregroen added [it]… should make it as easy as possible for components to communicate through more than simply DOM updates.
@peterbooker raised the importance of ease of access, for  … the [WordPress] development community… used to PHP, HTML, CSS, etc.
@mrmaniac (Paul Bakaus) added the best level of separation is if the framework is used to build the core, but isn’t exposed as API to block builders. This gives one the choice to replace the underlying foundation whenever necessary.
@mcsf said that for a project of the nature of WordPress, a framework should be relatively self-effacing, and its interface surface should be minimized and as agnostic as possible, mimicking the evolving JS specs.
@westonruter pointed out that If the underlying framework is being loaded on the page anyway, it should be available for plugin authors to utilize since otherwise they’d have to each include their own bundled frameworks… if core is shipping with one framework, then it would become the de facto framework by virtue of it being available out of the box.
@matias disagreed a bit with the idea that whatever core uses… is going to be the de facto standard for plugin development. The actual framework here, in general terms, is going to be what WordPress exposes and the APIs.
@flixos90 said I think core shipping a default framework and thus somewhat defining a standard to use is necessary to prevent compatibility issues by people using whatever framework (version) they like.
@mrmaniac (Paul Bakaus) suggested maybe there’s a middle ground, where, if you happen to use the same framework as the core, you benefit from the bundling, but if the core ever switches to another one, the framework gets lazy loaded in, and we create a mechanism that does this reliably.
@evanyou added I believe it’s important (and technically feasible) to separate “which framework to use for core” and “which framework community devs use for extensions”

 

The discussion moved on to interoperability and specifically ideas for providing a generic interface which can adapt to future change.

As background, @aduth put together two pull requests in Gutenberg on interoperability, one exploring combination of generic data structure / DOM access, and another using web components as the common interface:
https://github.com/WordPress/gutenberg/pull/2463 – Framework-agnostic block interoperability (Vanilla, Vue)
https://github.com/WordPress/gutenberg/pull/2791 – Support block `edit` defined as tag name for web components interoperability

@slightlyoff sees two major classes of interop: ease of development of leaf components and ease of integration of leaves into a larger whole.
@Justin Asked does anyone think that the custom elements lifecycle is not sufficient? At least for a foundation?

 

Discussion continued, largely focused around web components – how they could be leveraged for interoperability and how well they are supported in each framework.

@sophiebits (Sophie Alpert) added that in React, we have some web component support but haven’t made it a large priority since use cases have seemed slim in the past… but we do have some support for them nonetheless and I’m happy to entertain adding more, either now or in the future
@evanyou commented on the high level I think frameworks like React/Vue provides what is not really addressed in web components: efficient and declarative DOM updates reacting to state changes.. this is also why Polymer exists on top of WC
@Justin said that is ok: Web Components don’t need to answer _every_ question about components: they’re a foundation and interop layer
@trueadm added One major advantage of abstract components over web components is the fact they don’t live in the DOM. This gives several advantages – such as not being a global register custom element and being able to easily change/alter to an underlying layer as times change
@gaearon (Dan Abramov) added I’m not convinced custom elements are best interop layer. I would prefer plain JS hooks. On top of that, you can always add everything including them.

 

Discussion continued to patterns for pluggable interfaces, including the current use of react-slot-fill in Gutenberg and comparing it to <slot>. The meeting wrapped up with some discussion of how the choice of a framework for core impacts the wider community.

@gaearon (Dan Abramov) said I don’t really know WordPress well, so it’s hard for me to say whether [React is] a great fit for the use case or not… I think in general people have strong opinions about, for example, templating vs expressiveness, and I don’t feel like forcing React upon everyone is the best way. 

To which @evanyou responded I also feel the same way – forcing a single framework on everyone, regardless of which one, is IMO not a good idea because it is bound to alienate the group of devs who are not into that framework, and imposes a bigger long term stability risk.

 

Thanks to everyone who participated – especially to our guests from outside of the WordPress community: we welcome further collaboration with you in the future.

It is very clear (and refreshing to see!) from the conversation that the developers working on React, Vue and Polymer all care deeply about pushing the open web forward in a collaborative fashion. While we may not always agree on approaches, syntax or terminology, we do all agree that developers should be free to choose the platform and tools they find to be the best fit for their requirements. For WordPress core, this means that regardless of the framework we choose to use internally on projects like Gutenberg, we should ensure that the API we expose externally remains framework agnostic.

 

Add your voice and assistance!
We can use help especially testing @aduth‘s pull requests exploring interoperability: https://github.com/WordPress/gutenberg/pull/2463 and https://github.com/WordPress/gutenberg/pull/2791. Please read thru these PRs and test them out – see what works and what is missing, and give us your feedback.

Please join us next week at our regularly scheduled time Tuesday, October 3, 2017 at 13:00 UTC for the next JavaScript chat.

#core-js, #javascript, #summaries

JavaScript Chat Agenda for September 26th

Please observe the noted two-hour delay in scheduled meeting time.

The past few weeks have been eventful for the WordPress JavaScript community: First with the decision that WordPress would not use Facebook’s React project in developing core features, then a subsequent announcement by Facebook of their intention to relicense React and other open source projects. The time between was marked by lively discussion of frameworks and interoperability, which will continue as the topic of our next JavaScript chat.

Topic: The role of a JavaScript framework in WordPress, particularly as it relates to:

  • The requirements of core features
  • Considerations for plugin and theme developers
  • Framework interoperability
  • Future sustainability

When: Tuesday, September 26, 2017 at 15:00 UTC (Note: This is two hours later than the regularly scheduled time, in an effort to maximally accommodate all interested groups)

Where: #core-js Slack channel (Register)

For additional context, you may consider reviewing chat summaries from earlier this year relating to framework use in core (May 30th, May 23rd) or a recent GitHub issue which has garnered significant attention and discussion.

If you have questions related to the above agenda, please leave a comment. See you there!

#agenda, #javascript

JavaScript Chat Canceled for September 19

With the events of the past week relating to the decision to move away from React and the use of a hooks extensibility pattern, we are expecting the next JavaScript meeting to be very lively. Since many of the individuals leading these efforts and/or active in the discussions will be unable to attend, we have decided to postpone discussion until next week’s meeting on Tuesday, September 26, 2017 at 13:00 UTC.

The agenda for next week’s discussion will include:

  • The role of a JavaScript framework in current and future Core focuses (including but not limited to the Gutenberg editor)
  • Patterns of extensibility and use-cases for hooks

A reminder agenda will be posted ahead of the meeting on Monday, September 25.

#javascript

Proposal for JS Standards Revision: Removing Array/Function Whitespace Exceptions

Coding standards have been a recurring topic in the JavaScript Weekly Chat over the past few months. One rule in particular which has been the focus of much discussion are the exceptions for whitespace in arrays and function calls, which reads:

Always include extra spaces around elements and arguments:

[…]

Exceptions:

  • […] do not include a space around string literals or integers used as key values in array notation
  • Function with a callback, object, or array as the sole argument: No space on either side of the argument
  • Function with a callback, object, or array as the first argument: No space before the first argument
  • Function with a callback, object, or array as the last argument: No space after after the last argument

In the course of our chats, there has been some consensus around removing this “Exceptions” section entirely, though we considered to seek broader feedback on the decision, particularly in how it impacts overlapping PHP standards and existing code.

Why should this exception be removed?

The purpose of a coding standard should be to impose sensible rules for the sake of consistency and readability. In the case of consistency, a developer should be at ease both in writing and reading code.

The very existence of an exception is at odds with these ideals, harming consistency in that:

  • A code reader may not think to expect it if they are not familiar with the exception
  • A code writer may not know to apply it if they are not familiar with the exception. Or worse yet, one familiar with the rule may not know how to apply it.

The arrays and functions exception is notably egregious for being difficult to apply. Take, for example, the following snippet of code:

( function( wp ) {
	wp.foo = foo( 5, {});
	wp.bar(function() {
		console.log( 'Done' );
	});
	wp.baz( x, x + 5 );
	wp.baz(x => x + 5);
} )( window.wp = window.wp || {} );

This code is valid in its use of whitespace, but took considerable effort on the part of a developer well-versed in the standards to understand precisely where the exceptions do and do not apply.

Generally, exceptions increase the barrier to entry for new developers by imposing another prerequisite to becoming productive, increase overhead for existing contributors by requiring careful consideration of their application, and are anti-productive in the review hours wasted enforcing their inevitable mis-use.

Why should this exception not be removed?

All of the above notwithstanding, the exceptions concerning array or object keys at least have some basis in overlap with equivalent rules in the PHP Coding Standards. While I would argue that most all exceptions should be avoided, the focus of the first section is aimed primarily at function arguments, which tends to cause most uncertainty. It may be an agreeable compromise to remove only the exceptions impacting function arguments, leaving still the array and object key exceptions.

Standards changes should be carefully considered, as it has a large impact on existing code which applies the current standard, and on knowledge of developers who have already become familiar with the standards. However, my experience is that these exceptions aren’t particularly well-understood, and in-fact that eliminating them would be more in spirit with how whitespace is otherwise applied (“When in doubt, space it out.”).

What happens next if these exceptions are removed?

If consensus is reached, the following actions should be taken:

  • Our standards documentation are updated to remove the exception language
  • Our ESLint rules are updated to remove the exception
  • All new commits to WordPress core follow the new standards
  • Old code will only be refactored as part of a larger, codebase wide refactoring effort (see related effort at #41057)

What are your thoughts? Please share in the comments below.

#javascript, #standards

JavaScript Chat Summary for June 27th

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

  •  A post about the JavaScript framework decision for core is delayed to give more time for feedback.
  • The Weekly JavaScript chats will continue on the current schedule, however, we will no longer be posting agenda’s and summaries will be brief if posted unless something significant is happening, such as a new feature being merged.
  • A lengthy discussion about packages/modules ensued (related – #40834) and a packages repository was created to start collaborating on creating core WordPress JavaScript packages – https://github.com/WordPress/packages.
  • Several candidates were discussed and Yoast offered to donate their a11y package.
  • Discussion of namespacing,  repository management and documentation.
  • @youknowriad suggested we talk about build and test tools at the next meeting make sure to stay consistent with modules and how we use them.

Please join us next week at July 4, 2017 at 13:00 UTC in the #core-js slack channel, or visit at any time to get involved in contributing to WordPress core JavaScript.

#javascript, #summaries

JavaScript Chat Agenda for June 27th

Please join us for our weekly JavaScript Chat on June 27, 2017 at 13:00 UTC, where we will discuss:

  • No more agendas
  • Modules – What should we start moving into modules? How will these modules get integrated into core, workflows? How do we get started?
  • Big ticket items –  What tickets can we finish up in 4.9? Let’s make a plan to complete them.
  • Ticket Scrub/Open Floor

Important! All JavaScript chats will now take place in the #core-js Slack channel. Please join us there.

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#agenda, #core-js, #javascript