JS docs initiative: Add inline-docs for JavaScript!

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

x 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
  • 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
  • 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
  • wp-includes/js/wp-emoji.js
  • wp-includes/js/wp-list-revisions.js
  • wp-includes/js/wp-lists.js
  • wp-includes/js/wp-pointer.js
  • wp-includes/js/wp-util.js
  • wp-includes/js/wpdialog.js
  • wp-includes/js/wplink.js
  • wp-includes/js/zxcvbn-async.js

Current status:

Happy documenting!



Dev Chat Summary: November 15th (4.9 week 16)

This post summarizes the dev chat meeting from November 15th (agenda, Slack archive).

4.9 schedule + release timing

  • 4.9 release was delayed from yesterday (Tuesday, November 14th) to today (Wednesday, November 15th)
  • An updated 4.9 build went out earlier today, we still have to rebuild tinymce.min.js, but otherwise please test!
  • @afercia disagrees with patching last minute serious bugs without proper, broad, testing but deferred to decision by release leads
  • 4.9 release scheduled for later today (Wednesday, November 15th) at 3pm PST / 23:00 UTC
  • [Editor note: 4.9 released successfully! 🚀]
  • We’ll discuss post-4.9 / pre-5.0 plans later once we’ve had a chance to gather broader feedback on 4.9.
  • There is currently no timeline or plan for 4.9.x, but there are tickets currently slotted as 4.9.1 in Trac.

Meeting time changes

Gutenberg update

#4-9, #core, #core-js, #core-restapi, #dev-chat, #gutenberg, #summary

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 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

JavaScript Chat Agenda for June 20th

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

  • WordCamp Europe recap. JavaScript was a popular topic during the events surrounding WordCamp Europe, notably last week’s Community Summit and Contributor Day. Let’s recap these discussions and the action items set forth.
  • Increasing JavaScript contributions in core. How do we increase contributor involvement in core JavaScript and the number of contributors? This is an extension of an identical discussion which had taken place during WordCamp Europe’s Community Summit.

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

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