Dev Chat Summary: October 10 (5.0 Week 2)

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

5.0 planning

  • See @pento’s WordPress 5.0 for Contributors and Committers post:
    • “If you’re an experienced contributor or committer who has time available during the WordPress 5.0 release cycle, and want to be able to make meaningful contributions towards making WordPress 5.0 awesome” … “Please reply to this post with information about your availability, what components of WordPress you have experience in, and (if you haven’t got involved with Gutenberg yet) what you feel has been getting in the way.”
    • In that post are some direct actions you can take to help contribute to 5.0, otherwise please review and comment if you’ll be around during the 5.0 release cycle… thanks!
  • Also see review @pento‘s 5.0 commit/branch details if you plan to contribute during the 5.0 release cycle
  • @pento: if you have time to help, please review tickets in the 5.0 milestone to determine whether to keep it in 5.0 (Gutenberg-related), or move to 5.0.1 (other bug fix) or 5.1 (other feature)
  • @kadamwhiterequest for help testing Lazily Evaluate Translation Strings (#41305) with input requested by the end of this working week to help remove the blocker to further Gutenberg localization work
  • Plans for an updated readme.html to be committed with contributions open until RC
  • @chanthaboune: collecting blocker items and dates across team reps, will post listing to Make/Core, if you have items to add to the listing please ping @chanthaboune directly
    • @matt: 5.0 baseline and goal is 4.9.8 + Gutenberg, thus a lot of things that may have been considered blockers in past major releases are probably going to be reclassified as “nice to have”
  • @matveb: last JS package included in the Gutenberg 4.0 RC, on track and could be ready for end of the week

Updates from focus leads and component maintainers

General announcements

  • See @matt‘s post for details on the Gutenberg Phase 2 Leads, @alexislloyd (design and product) and @youknowriad (technical)
    • Phase 2 is about thinking outside the box, namely the post and page box, to allow Gutenberg to handle entire-site layouts. We will replace widgets with blocks, so any block will be able to be used in any registered “sidebar” for legacy themes, and we will upgrade “menus” to a navigation block.
    • Phases 3 and 4 of Gutenberg at WordCamp US in December.
  • @audrasjb: a11y team reorganizing, will discuss during next week’s meeting
  • @chanthaboune: as teams identify new/updated team reps, please follow notes on team rep orientation

Next meeting

The next meeting will take place on October 17, 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.

#5-0, #a11y, #core, #core-editor, #core-js, #core-media, #core-php, #core-restapi, #dev-chat, #gutenberg, #summary, #team-reps

Technical overview of Gutenberg integration

To better understand how we can integrate Gutenberg into WordPress, it’s crucial to know how the Gutenberg plugin is organized.

JavaScript Packages

The Gutenberg plugin is mostly a JavaScript application composed of several packages. Each one of these packages is:

  • Generic and available as an npm package.
  • The Gutenberg Plugin registers each package as a WordPress script.
  • The Gutenberg Plugin makes the public API of each package available in the wp global variable.
  • If a package is dependent on another one, it consumes it as a global variable and adds it as a dependency of the WordPress registered script.
  • A package can have one or multiple CSS stylesheets.

For example:

A @wordpress/components npm package is registered in the plugin as a wp-components WordPress script; its API is available in the wp.components global variable; and depends on @wordpress/element.

In turn, @wordpress/element‘s script is wp-element and is consumed by @wordpress/components in the bundled script as wp.element.

Bootstraping the editor’s page

To display the editor’s page we call wp.editPost.initializeEditor from the higher-level wp-edit-post package. This function takes as arguments the post to be edited and some editor settings.

This call is made when loading the edit.php page localizing the required arguments and enqueuing the wp-edit-post script.

REST API endpoints

Once the editor’s page rendered, all the communication with WordPress happens using REST API calls. In addition to the regular REST API endpoints to fetch, update and delete taxonomies, posts, etc., Gutenberg adds new REST API endpoints that include:

  • Autosaving endpoint.
  • Reusable Blocks endpoint.
  • Root endpoint for site settings.

Many other tweaks have been necessary in existing endpoints (taxonomies, embeds, permalinks, post search, etc) and most of these have been merged in the previous 4.9.* releases.

MetaBoxes

To support MetaBoxes, Gutenberg hooks initially render the content of the MetaBoxes in a hidden DOM node rendered using a PHP script. We also hook into the post.php call to persist the MetaBoxes save call.

Summary

So, as a high-level picture, the Gutenberg plugin is composed of:

  • JavaScript scripts and styles.
  • A PHP file to bootstrap the editor in edit.php.
  • REST API endpoints.
  • PHP utilities to parse, register and render blocks on the front-end.
  • PHP script to inject the MetaBoxes into the page and hooks to save the MetaBoxes.

Integration Process

In previous JavaScript meetings, we discussed the packages integration approach:

Since the JavaScript scripts are built as reusable npm packages, we’ll consume them in WordPress like any other npm package:

  • Adding a dependency in Core’s package.json.
  • Exporting the wp.* globals in enqueue scripts inside WordPress Core.
    • Example: wp.components = require( '@wordpress/components' );
  • Moving the script registration corresponding to each package into wp-includes/script-loader.php.

Scripts like wp.shortcodewp.a11y.speakwp.utils.WordCount can be replaced by their corresponding npm packages. This has already been proposed for the shortcode package and should continue for other packages.

The work being done in #core-js meetings to align the JavaScript guidelines (code style) between Gutenberg and Core would result in a formal @wordpress/eslint-preset package that should be used as a replacement for the current JSHint config.

The REST endpoints should be moved to the regular REST endpoints location in WordPress Core wp-includes/rest-api/endpoints.

The PHP utilities and classes should be moved to wp-includes.

Some minor tasks are also left to do in the Gutenberg repository:

  • Drop the Gutenberg name from all the PHP APIs still using it.
  • Finalize the block-library and edit-post packages:
    • HTML Block and Freeform block to be moved to the npm packages.
    • The creation of the edit-post package.

Test Suite

The e2e tests are crucial to avoid regression when making updates to WP-Admin. The e2e test infrastructure and the tests themselves should be moved to WordPress Core and their stability can be considered a metric for the success of the integration process.

Unit tests, in general, live next the code being tested. For packages, these will stay in the Gutenberg repository and, for the files moved to Core, the tests will follow.

What about the Gutenberg Plugin?

After WordPress 5.0 is released, the Gutenberg plugin will continue to exist. Its purpose will be changed to the development and the maintenance of the WordPress npm packages, including the editor itself, and will also serve to develop the second phase (site customization) of the Gutenberg project. Plugin updates will continue to be released during the 5.0 cycle.

The PHP part of the plugin won’t be needed anymore, as the plugin will just register new versions of the scripts of the packages to replace the ones already registered by Core.

Dev Chat Summary: September 26th (4.9.9 week 7)

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

4.9.9 and 5.0 updates

  • @schlessera: just about time to begin work on the 5.0 release cycle
    • @antpb and I will step back as release leads and wind down the 4.9.9 release
    • Over the next couple of weeks we will start coordinating the transition to ease into 5.0 release cycle
    • Will review the work that teams are already in the middle of and determine how best to proceed
    • Announcing this change as soon as possible to provide a longer transition period to smoothly transport as much work over as possible
  • @chanthaboune: “I lead the open source teams at Automattic and am a full time sponsored volunteer to the WordPress Project.”
    • We will reach out to team reps, discuss what you’ve been working on, and what we can do to keep things moving forward so that we can make sure everyone is heard as we settle in for 5.0
    • Current understanding is that @matt is leading 5.0 and any other leads are yet to be determined
  • @jorbin: concern with canceling 4.9.9 due to upcoming PHP7.3 release, some things need to be done to make sure WordPress runs fine on this new version of PHP, I want to ensure the version of WordPress in use on December 13th is compatible with PHP7.3, a very small scoped 4.9.9 may still be needed from myself and ideally @sergeybiryukov @pento @schlessera as well
  • @desrosj: #44416 and #44771 appear to be the open PHP 7.3 compatibility tickets in Trac
  • @pento: seems possible to wrangle a small 4.9.9 release with PHP 7.3 related bug fixes, while 5.0 is ramping up
  • @matveb: Gutenberg leads are near ready to start planning merge proposal for Gutenberg, currently focused on finishing the core Gutenberg tasks, @youknowriad has made a proposal for how JS packages could work
  • @youknowriad: recommend iterative merge vs. a big merge proposal, technical proposal on how this would work was shared in #core-js meetings
  • @sergeybiryukov: some new hooks or enhancements already backported to the 4.9 branch, will need to determine whether or not that should be reverted
  • @jeffpaul: in summary… (1) it appears like a possible agreement with @jorbin @pento (and possibly others who’ve been “voluntold” but yet to confirm) to work on a 4.9.9 focused solely on PHP 7.3 support and (2) @chanthaboune will review existing 4.9.9 work with team reps to see how that should be handled with the 5.0 cycle likely starting shortly

Updates from focus leads and component maintainers

  • The Editor / Gutenberg team released v3.9 last week including the ability to create reusable templates of blocks and exporting them to a JSON file
  • The JavaScript team posted this week’s meeting summary and specifically called for help looking for npm maintainers, so please let them know if you’re interested and available. Related to that, @youknowriad shared #44987 and is looking for review there.

General announcements

  • @psykro continues to look for review and feedback on the alternate devchat proposal
  • @joyously: Theme Review Team discussing what to allow theme authors to put in the admin, possibly allowing themes the same interface as plugins do with a readme.txt file and a View Details link to enhance the theme documentation, change logs, screenshots, upsells. Will look to have discussion in Core Trac ticket or Make/Themes post (and cross-post to Make/Core).

Next meeting

The next meeting will take place on October 3, 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.

#4-9-9, #5-0, #core, #core-editor, #core-js, #dev-chat, #gutenberg, #summary

JavaScript Chat Summary – September 25th

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

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

Packages

Shortcode in Core

(Slack Conversation)

@youknowriad proposed a pretty exciting change which would allow to consume the existing @wordpress/shortcode npm packge in WordPress core. It’s ready for testing and gathering feedback.

Issue: https://core.trac.wordpress.org/ticket/44987

Once it lands in core, it will enable further integrations with the packages like @wordpress/a11y, @wordpress/api-request, @wordpress/wordcount, etc. This is going to pave the way to integrate Gutenberg in core.

Call for npm maintainers

(Slack Conversation)

We have only 6 team members which are able to publish updated npm packges to npm. We would love to extend this group to have more flexibility and better coverage when people take time off. 

We also discussed that we should start publishing updates to packages on regular basis like once a week. Preferably before the weekly JS chat.

@noisysocks volunteered to help with the upcoming release 🎉 Let us know if you are willing to join the group.

Open Floor

Update on Mobile Gutenberg 

(Slack Conversation)

Kudos to @hypest for adding tests for Mobile Gutenberg in Gutenberg’s Continues Integration job. This is the first step towards merging those two repositories together and bring their development process even closer. It will help us prevent introducing changes which would break the mobile project.

#javascript #core-js

Dev Chat Summary: September 19th (4.9.9 week 6)

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

4.9.9 planning

  • @westonruter: highlighted this discussion about the scope of HTTPS support to target in 4.9.9
    • Looking for wider visibility on those items to get thoughts on what makes sense to include in 4.9.9
    • Relates to umbrella ticket #28521
  • @audrasjb: Accessibility team has a spreadsheet where we sort all the tickets on the focus a11y in order to facilitate lead’s work (see this week’s meeting notes)
  • Bug scrubs not scheduled yet, when they are it’ll be posted to Make/Core

Updates from focus leads and component maintainers

  • @kadamwhite from the REST API team wants to propose the inclusion #41305 in 5.0
    • This covers altering how we evaluate translation strings, originally with the intent of deliberating a performance improvement to the REST API. In discussions about how Locale can be applied to REST API responses for Gutenberg this issue resurfaced, because the current order of operations precludes evaluating string translations based on a passed flag (required to permit the API to provide translations in a user’s locale). To support these localization needs and to improve overall performance at the same time, we intend to milestone this ticket for 5.0.
    • @schlessera: There are two proposed solutions in the above ticket: one that fixes REST API schema translations only, and one that generally optimizes translations (REST API component team’s strong recommendation). The latter is highly preferable, but includes breaking changes for edge cases (as noted in the ticket), so might need a check against plugins first. We otherwise would like more eyes on the forthcoming patch to validate the approach and to help test it.
  • The Editor / Gutenberg team released v3.8 last week including “full screen” mode, improved mechanisms for styling blocks from a theme perspective, and exposes the custom post type used to store reusable blocks from the block inserter as a way to manage saved blocks in bulk.
  • The JavaScript team published notes from their last meeting including documentation of available Gutenberg scripts, reducing exposure of Moment.js in the `wordpress/date` module, and a couple announcements on introducing a formal asynchronous data flow as part of `wordpress/data` and the new `wp-polyfill` script added to Gutenberg.

General announcements

  • @psykro posted about alternate devchat options. Please give that a review and feedback, as ideally we get to a conclusion during next week’s devchat.
  • @whitneyyadrich & @dkotter looking for eyes on / update to Gutenberg issue#7762 as they are running into an issue where they need to be able to insert and manipulate media attachments within the Classic Block, but that’s not currently possible
    • Also imagine this being a bigger issue when migrating sites over to Gutenberg and all their existing content will be thrown into that block. There’s currently not a great way for them to modify/add to that content, if they need to do things with images.
    • Will review with Gutenberg team in next #core-editor weekly chat

Next meeting

The next meeting will take place on September 26, 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.

#4-9-9, #a11y, #accessibility, #core, #core-editor, #core-https, #core-js, #core-restapi, #dev-chat, #gutenberg, #javascript, #summary

Dev Chat Summary: August 08, 2018 (4.9.9 Week 1)

This post summarizes the weekly dev chat meeting held Wednesday, August 08, 2018 (agenda | Slack archive).

👉🏼💥 Release Lead Nominations 💥👈🏼

It’s time to select release leads for our 4.9.9 maintenance release. Hooray! If you’d like to nominate someone, or yourself, add a comment to this post. Don’t be shy, y’all.

What does a release lead do? Here are some good resources: 

🔥 Hot Tip 🔥 You don’t have to be an engineer to be a release lead.

4.9.8 Release Feedback

  • Check the goodies in the maintenance release post, if you haven’t.
  • Big thanks to @pbiron, @joshuawold, @sergeybiryukov, @psykro and Mission Control. 🙌🏼
  • @pbiron plans to post a retrospective similar to this in the next week or two.
  • Overall, the Try Gutenberg callout has been effective in getting people to use Gutenberg and find bugs. Active users jumped from 20k to 100k in just a few days. 
  • The support team reports via @clorith things have been pretty quiet since the release. More info inbound on wider areas of focus for support, so stay tuned.
  • There are some reported issues to jump on:

4.9.9 Planning

  • We’re all going proceed as if we’re doing a 4.9.9 maintenance release, so keep working on the growing list of tickets here.
  • However, as of today, we aren’t committed to a 4.9.9 maintenance release. Why?
    • There is not a rush to get a maintenance release the door
    • We don’t have committed leads yet (see above)
    • So far, we don’t have any significant issues from 4.9.8 that require attention

Focus Lead and Component Maintainer Updates

REST API

  • The REST API meeting is today – August 9, 2018 – at  17:00 UTC. Welp, this already happened.
  • The key agenda items are: 
    • Prioritize register_meta improvements for 5.0
    • Review API-related Gutenberg tickets
    • Selecting and prioritizing additonal backlog tickets for 5.0

JavaScript

Gutenberg

Thank you to all who gave us feedback so far! The feedback is being processed and iterations are underway. 

Open Floor

Post counts on on shared taxonomy terms 

Via @davecpage. There are multiple tickets open related to this:

These are all related to the taxonomy component, and we’ll currently slate them for release in 4.9.9.

General Announcements

Dev Chat Coordination: The Sequel

@jeffpaul is ill and will hopefully return next week. Until he’s at full strength, @joemcgill@audrasjb@antpb and I will continue to run dev chat.

Next Meeting

The next meeting will take place on Wednesday, August 15, at 20:00 UTC in the #core Slack channel. Please drop in with any updates or questions. If you have items to discuss, drop a comment on next week’s agenda post, so we can take them into account.

Dev Chat Summary: June 27th (4.9.7 week 6)

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

4.9.7 planning

  • Confirmed @pbiron and @joshuawold as co-release leads with @sergeybiryukov and @psykro as co-deputies
  • Likely focus for 4.9.7 to be “Try Gutenberg” prompt and privacy fixes
  • Release timing for 4.9.7 will be confirmed amongst release leads and shared when ready
  • Consensus that release leads have previous contribution experience (not necessarily Core contributions), also helpful that a lead or deputy has commit access
  • Aiming to expand roster of individuals who have experience leading releases, so one approach is pairing “new” leads with “experienced” ones though other candidates could feasilby be experienced enough to not require a co-lead
  • Though no defined process exists on selecting or confirming leads, if someone has concerns about a nominated lead they can directly talk with @jeffpaul if they’re not comfortable speaking up during the devchat though ideally concerns are more transparent or at least leverages a group and not a single entity to coordinate concerns appropriately

Updates from focus leads and component maintainers

  • The Gutenberg team released v3.1 and published release notes as to the updates included
  • The JavaScript team published notes from their meeting where they discussed sunsetting the packages repository, an alternative to wp.apiRequest, a deprecation strategy, data module improvements, the build process, and inline docs. Many thanks to them for continuing to share notes from their chats
  • Reminder to focus leads and component maintainers to try and publish meeting notes from your chats to help socialize what’s happening across the different teams in #core.

Devchat coordination

  • @jeffpaul will be offline most of July, so @joemcgill, @audrasjb, and @antpb will help coordinate devchats (collecting agenda items and publishing an agenda, running the actual devchat meeting, and publishing a devchat summary). post-devchat note: @whitneyyadrich also volunteered to assist with devchat coordination

General announcements

  • @jeffpaul: some comments lately about security issues and the security team, reminder about responsible security disclosures, people’s views will be better received if they’re formed as offering solutions to problems rather than continuing to point out problems
    • @paragoninitiativeenterprises: recent security advisory showed longer ETA than expected, security team needs more resources (e.g., personnel) and it falls upon the community to ensure the security team has the manpower it needs
    • @jeffpaul: anyone who feels they have the ability and interest to contribute to WordPress Security should reach out to @aaroncampbell
  • Effort from .ORG to contact hosts with large amounts of WordPress installs to help manually update sites from 4.9.3, current count hovering over a million sites but down significantly, still working with some groups (e.g., Google search console team) to try to get more people updated

Next meeting

The next meeting will take place on July 4, 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.

#4-9-3, #4-9-7, #core-js, #dev-chat, #gutenberg, #security, #summary

Dev Chat Summary: June 20th (4.9.7 week 5)

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

4.9.7 planning

  • Leads nominated so far: @sergeybiryukov able to help as deputy (e.g., committing, backporting); @danieltj, @tristangemus, @pbiron, and @danielbachhuber open to help contribute during 4.9.7
  • Potential focus for 4.9.7 so far “Try Gutenberg” prompt and privacy fixes
  • Release timing for 4.9.7 will be determined after a release lead is named
  • No confirmed interest in release leads from other team reps and component maintainers or from WCEU, but #design team likely in future minor releases
  • Looking to increase diversity in release leads by asking for nominations or suggestions outside just devchat and summary posts, please share any ideas you have on this… thanks!
  • For those with interest and availability, please review the Releasing Minor Versions handbook page and the Release leads feedback on 4.9.5 post
  • Will look to make decision on 4.9.7 release leads in next week’s devchat

Devchat coordination

  • @jeffpaul will be offline most of July, so we’ll need someone to help coordinate/run devchats
  • So far @joemcgill, @audrasjb, and @antpb have graciously offered their time, hoping for 1-2 more people to help to help share the load
  • If you’re open to collecting agenda items and publishing an agenda, running the actual devchat meeting, and/or publishing a devchat summary then please comment here or ping @jeffpaul if you’re able to help out… thanks!

Updates from focus leads and component maintainers

  • The Gutenberg team would like to encourage testing of the next few releases as they get closer to feature complete
  • The JavaScript team shared an update on the process of adding inline docs, so if you’re interested and able to contribute please check it out. They also posted a summary of their meeting covering documentation, polyfills, and deprecation strategy for WP JS code.

Next meeting

The next meeting will take place on June 27, 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.

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

JavaScript Chat Summary – June 19th

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.

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 (@igorsch)
  • 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 (@digitalarticle)
  • 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 (@dfangstrom)
  • 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 (@boblinthorst)
  • 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