The WordPress core development team builds WordPress! Follow this site for general updates, status reports, and the occasional code debate. There’s lots of ways to contribute:
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
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:
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.
@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.
Two separate issues were raised regarding the deprecation strategy:
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
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.
@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.
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.
svn up) or Git repo (use git pull) to the latest version of WordPress trunk.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.
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.
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.
Checked files are completed, marked files are claimed
Current status:
Happy documenting!
This post summarizes the dev chat meeting from May 16th (agenda, Slack archive).
The next meeting will take place on May 23, 2018 at 20:00 UTC / May 23, 2018 at 20:00 UTC in the #core Slack channel. Please feel free to drop in with any updates or questions. If you have items to discuss but cannot make the meeting, please leave a comment on this post so that we can take them into account.
Back in 2016, work started on building a proper JavaScript internationalization API and the tooling to support it throughout WordPress core and WordPress.org. Many ideas and patches were being discussed. A summary of that can be found in this blog post. With Gutenberg on the rise, JavaScript I18N is more urgent than ever. WordPress needs a robust solution for that, and some things have already been built. Let’s have a look at where we currently stand.
Right now, Gutenberg is using a custom built JS I18N library that is similar to the one originally proposed in 2016 as part of #20491. It lies on top of a library called Jed which bring Gettext functionality to JavaScript. This means developers can use the same __() function as in PHP and therefore don’t have to learn anything new. WordPress can take it from there.
Unfortunately, WordPress doesn’t yet support JS I18N library. Gutenberg (or any other plugin that uses said library, really) has to jump through quite some hoops to actually localize their JavaScript:
wp_add_inline_script(). Ideally you’d only load the ones needed by that specific script as you don’t want to print thousands of strings in that inline JS when you only need a few of them.An example of that process can be found in my demo Gutenberg I18N Block plugin.
At this point you might want to go back to good old wp_localize_script() and simply keep using that for internationalization purposes. I don’t blame you.
However, this complicated process is only needed because the work on JavaScript internationalization is far from done yet. Gutenberg made it quite obvious where things need to be improved.
First and foremost, the WordPress.org translation platform needs to be able to scan JavaScript files for internationalization functions in addition to just the PHP files. However, that’s not as straightforward as it sounds.
The platform uses a script called makepot.php to scan PHP files all across the WordPress.org ecosystem, i.e. core, meta, and all default themes. In addition to regular Gettext function calls it also scans plugin and theme file headers. Being included in many other libraries, makepot is a widely used tool. Most recently, its functionality was ported to a WP-CLI command to make string extraction easier to use.
On the other side we have babel-plugin-makepot, a tool written in JavaScript to scan JavaScript files. With the ECMAScript standard evolving so quickly, it is natural to write such a tool in the same language. However, it’s not a requirement, as this pull request for said WP-CLI command demonstrates. This opens some questions:
Can we simply use that Babel plugin on WordPress.org? What happens to makepot.php? What are the implications for all the developers out there not hosting their projects on WordPress.org? Not everyone uses the Babel transpiler, and certainly not everyone wants to use two separate tools just to extract some internationalization functions.
All translations for a plugin or theme are stored in one single PO / MO file per locale. Loading these translations is a slow process. We’ve made some improvements in that regard over the years, for example by introducing just-in-time loading of translations in WordPress 4.6.
However, if you only need a handful of translations for a single script in your plugin, it does not make sense to load the entire MO file which can be dozens of kilobytes in size. There’s currently no way to load only a specific set of translations in WordPress. This is something that came up in Gutenberg before, see issue 6015.
Binary MO files don’t make sense in a JavaScript context anyway. Lucky for us, GlotPress—the software that powers translate.wordpress.org—has been able to export translations in a Jed-compatible JSON format since 2016. We just need to use that to export a JSON file for all strings extracted from JavaScript files
So in theory the WordPress.org translation platform could export PO and MO files as usual for strings extracted from PHP files, and a JSON file for all strings coming from JavaScript files. This would be already a huge improvement. But can we take this even further?
Use a different text domain per JavaScript module. Export a JSON file per text domain. This is appealing, but has to be ruled out quickly: the text domain is not known to GlotPress and is not stored in the database or anything.
GlotPress doesn’t know about the text domain, but it does know a string’s source file. What if it would export one JSON file per source file it has scanned? This way WordPress has full control over the translations and one could specify which JSON files need to be loaded for a specific module.
The big drawback here: a single module might consist of dozens of source files. Having one JSON file for each of those is not going to scale well.
The built JavaScript file can’t be scanned either, because tools like UglifyJS rename functions and strip out comments.
Don’t do anything fancy. Sticking with a JSON file already guarantees that a plugin doesn’t unnecessarily load all the translations needed just in PHP. So the file size is definitely smaller. Still, this file alone can be very large for an application like Gutenberg.
Keep one single JSON file for all translations, but use some PHP code to only ever pass the strings to a module / script handle that it actually needs. However, there’s probably no real benefit in doing so.
Up until WordPress 4.6, developers needed to use load_plugin_textdomain or load_theme_textdomain() to make sure translations are properly loaded. Now, you only need to use the various translation functions and the rest just works. The only requirement is that your translation files reside in wp-content/languages. This is usually the case when your project is hosted on WordPress.org.
We should aim for a similar experience for JavaScript translations as well. While just-in-time loading of translation files via HTTP isn’t really possible due to the asynchronous nature of JavaScript, WordPress should still make it as easy as possible.
Imagine having a plugin foo-plugin and you’re enqueuing your JavaScript like this:
wp_enqueue_script( 'foo-script', plugins_url( '/foo-script.js' , __FILE__ ) );Ideally, all you’d need to do to translate it is calling a function like load_js_textdomain( 'foo-plugin' ). WordPress would then do all the heavy lifting.
However, other options might exist, and this solution would need to be tested in the wild with bigger projects like Gutenberg.
Bringing a JavaScript I18N API to WordPress will have a huge impact. We need to make sure we end up with a solid plan that works for as many plugins and themes as possible.
Ideally, we hold a separate JS I18N meeting with all the teams primarily involved: #core-i18n, #core-js, #core-editor, #meta-i18n and #cli. Everyone is welcome to attend though 🎉
I suggest the following date for such a meeting: Tuesday, May 8 15:00 UTC. Of course I’m open for other suggestions. The Slack channel would be #core-i18n.
At this meeting we can discuss the missing pieces outlined in this post and the overall next steps for JavaScript I18N in WordPress.
If you have any questions or concerns about this post or the overall topic, please leave a comment below.
+make.wordpress.org/polyglots
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.
svn up) or Git repo (use git pull) to the latest version of WordPress trunk.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.
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.
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.
Checked files are completed, marked files are claimed
Current status:
Happy documenting!
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
@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.
Below is a summary of the discussion from this week’s JavaScript chat (agenda, Slack transcript):
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.
Please join us for our weekly JavaScript Chat on June 27, 2017 at 13:00 UTC, where we will discuss:
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!
Please join us for our weekly JavaScript Chat on June 20, 2017 at 13:00 UTC, where we will discuss:
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!
