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

JavaScript Chat Summary for June 20th

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

WordCamp Europe Summary

  • Contributor day drew 500 attendees and included two JavaScript-focused sessions
  • Sessions overflowing-packed, indicating huge and growing interest in using JavaScript in WordPress
  • Anyone involved in JavaScript is encouraged to consider giving a WordCamp talk to share your experience
  • During community summit, recap of framework discussion and review of recent core chats
  • Notes from Community Summit will be posted soon, including a decision surrounding the recent framework selection discussions and the rationale leading to it

Increasing JavaScript contributions in core

  • Observed very small number of contributors
  • Introduction of a new #core-js Slack channel toward goal of engaging new contributors looking to become involved in WordPress JavaScript (link to 300 open tickets)
  • Question: What factors increase developer involvement and how can we increase involvement?
  • Contributor experience: Workflow of using Trac and exchanging patches not welcoming to new generation of (JavaScript) developers using Git and GitHub
  • Gutenberg as as an example of a WordPress project being built in GitHub, easy way to become involved
  • Previous efforts relating to GitHub pull request integration with Trac (#34694, rmccue/github-to-patch)
  • Increase involvement by sharing generic modules in a WordPress modules monorepo, drawing awareness from developers engaging in these ecosystems (npm, etc)
  • In-progress side project from @atimmer to parse and publish documentation to DevHub using documentation.js
  • Lack of documentation cited as pain point for new contributors. Should improve overview-type developer guides for using and extending core JavaScript.
  • New contributors would like quick start tasks to work on. “Good First Bugs / Tasks” exist in Gutenberg and in Trac (filtered to JavaScript focus)
  • Contributions are slow to be reviewed or committed, perhaps discouraging new contributors
  • Yoast has started efforts to improve documentation for media library. We might consider moving these discussions into Trac to surface and organize them as core issues.
  • Is WordPress’s image in JavaScript communities as “old” (or otherwise undesirable) as being a deterrent? Possible solutions: Blogging about innovations, sharing useful utilities in broader JavaScript community, evolving foundation for JavaScript with efforts like Gutenberg, highlighting JavaScript improvements in release notes
  • New contributors might consider simply reviewing existing tickets, testing whether they’re still valid, taking screenshots, and commenting

Administrative

  • Weekly meeting agendas will become more minimal over time with focuses on bug scrubs and deciding larger item tickets (dates, hooks, etc)

#javascript, #summary

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

JavaScript Chat Summary for June 6th

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

Pre-Discussion

Topic: Managing Complexity

  • WordPress is first development experience for many, and we should ensure JavaScript onboarding is similarly positive
  • Documentation as lacking
    • Current state of the wp global documentation
    • Documentation is always an after-thought
    • We can try automated documentation, but it’s not human-oriented and helps only if you know already what you’re looking for
    • We’ll need a combination of both automated and hand-written documentation
    • Need higher-level documentation to answer the questions of “How do I do X?”
    • User-submitted code examples like those on developer.wordpress.org are effective beyond just what the API is, but also how it’s to be used
    • To start, we need a 10,000 foot view explaining surface area of JavaScript in WordPress (expanding Core Handbook)
    • Who is the target audience of documentation: those looking to integrate, or contribute directly to the core codebase? Each requires different writing approaches.
  • Identifying challenges
    • Preparing a development environment and knowing where to find source files, especially in light of desire to more heavily adopt Webpack into workflow
    • Understanding decisions made: Why a framework, how do we approach data, how data is stored
    • Ideal workflow to npm start and be set to develop
    • Testing, build tools, module patterns
  • What to document?
    • Documenting UI components is new consideration. React Storybook was raised an example for demonstrating shared UI library (proposed in Gutenberg)
    • Bridging the divide between Backbone + Non-Backbone (“new”) system
  • Where to draw the line between complexity and unfamiliarity?
    • No amount of documentation can make up for a confusingly complex design
    • Some level of unfamiliarity is expected because it’s a different language with different paradigms than what a PHP developer might be most familiar with (example: declarative, reactive components)
    • We sell ourselves short if we limit only to what people already know
  • Incrementally introducing more complex functionality
    • What are the small tasks that developers will start with in getting used to working with WordPress JavaScript? “Writing an editor (Gutenberg) block” is a more advanced case, but highlights need for emphasis on the interfaces we expose, not just the documentation
  • Audience of documentation
    • People learn differently: Video works best for some, text for others
    • Might consider building personas to represent different users of documentation
  • Tools for documenting
    • We should standardize on JSDoc, but available tooling is somewhat lacking
  • Examples / success stories
    • Vue / React / Redux – Incremental introduction
    • documentation.js – Static analysis tool for creating documentation
    • React Storybook – Interactive UI component explorer
    • Calypso (Note: pages have layout issues if not logged in to WordPress.com)
  • Thoughts on scaffolding / code generation tools, like vue-cli, create-react-app, or more granular scaffolding like those found in Ruby on Rails or Laravel workflows (models, controllers, etc).
    • Not sure yet what sorts of things we’d care to generate
    • Could be valuable in “Age of Front-End Tooling Complexity”
    • Works for some people, not for others

Open Floor

  • From a comment on the agenda, @omarreiss shared a proof of concept for React extensibility, and was happy with control React gives toward goal of extensibility
    • Other approaches were shared: Nylas plugins, Gutenberg considerations (1, 2, 3)
    • “Extensibility” proposed as a future meeting topic
  • @rmccue shared his success with rendering PHP-only columns in the List Tables prototype toward a goal of backwards compatibility, and invites for consideration whether this is something we’d want for wider use or if others have encountered similar issues.

#javascript, #summary

JavaScript Chat Agenda for June 6th

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

  • Managing complexity. From the discussion following the frameworks discussions of the past two weeks, it has become clear that developer onboarding will be a critical consideration as we expand the role of JavaScript in WordPress. Where do we anticipate challenges to occur, so we know where to focus our efforts? What are some examples of success stories in developer experience, and of those, what specific lessons can we apply in WordPress JavaScript? What tools can we leverage to automate the creation of useful, up-to-date documentation?
  • Open floor

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!

Note: Due to a timing conflict with WordCamp Europe’s Community Summit, there will not be a meeting next week (June 13th).

#agenda, #javascript

JavaScript Chat Summary for May 30th

Foreword: The topic of integrating a new JavaScript framework in WordPress has proven to be both lively and contentious. The summary that follows is a best effort at an objective and accurate recap, but you are encouraged to review the original Slack transcript for the complete unaltered context (Slack registration required).

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

Introduction

  • The conversation that followed from last week has taken heavy aim at considering only React and Vue as candidates. Have we been certain to exhaust all other options?
  • Backbone features will continue to be maintained in core for the foreseeable future
  • The decision to be made is one affecting new features to be built
  • Developers will still have flexibility in choosing their preferred tools for themes and plugins
  • We need to know what we’re building in order to make sound technical decisions. This year’s focuses can serve as a start: the post editor (Gutenberg), Customizer expansion in moving toward theme building functionality, and REST API-based reimplementations of existing features (examples including Quick Draft, post listing)

Alternative Suggestions

  • Deciding on React as the framework of choice in WordPress.com Calypso was the result of prototype implementations of various frameworks (at the time, 3+ years ago) and judging the success of each.
  • Preact could serve as a stand-in for a React-like paradigm if we consider ourselves blocked by React’s patent grant or ideological differences between Facebook the company and WordPress the project.

Contrasting Candidates for Consideration

The bulk of the conversation considered the merits of React and Vue only, largely contrasted on the basis of developer onboarding, ideological alignment between WordPress and for-profit companies, and the extent to which each sets the foundation for successful future maintenance of the features we seek to implement.

  • Vue in practice: There have been no examples surfaced for projects relating to WordPress and the sorts of features we want to build (examples welcome in comments).
  • Ideological implications: We should consider what it means to align WordPress with any particular framework. There’s a worry that the values of Facebook as a company are at odds with those of WordPress.
  • Concerns about React: its learning curve and licensing (specifically, a termination clause included in its patent grant)
  • React is a pattern as much as it is a library, as evidenced by proliferation of compatible libraries like Preact, Inferno, Rax, and others.
    • Patterns emphasizing declarative rendering, one-way data flow, and embracing JavaScript the language. WordPress has historically stayed true to the fundamentals of the languages, largely foregoing template languages or other domain-specific languages in PHP.
  • Embracing JavaScript the language
    • Building rich applications is not comparable to history of applying JavaScript minimally in small interactions. Modern JavaScript is necessarily more involved to learn than a library like jQuery because we are building more complex functionality.
    • Are we really setting a foundation for developers to succeed into the future if we obscure the language with a template language like Vue’s (logic example)? Are we being inviting to new developers who began programming using JavaScript, or providing skill-learning opportunities that are broadly applicable?
    • Vue offers render functions similar to React, but their existence could undermine the perception of Vue being simpler if we’re acknowledging that the limits of the framework necessitate additional paradigms encompassing the entirety of React. Or is the argument of React’s complexity something else?
  • Conversely, there is a strong sentiment that Vue has a much friendlier developer onboarding experience. WordPress has prospered by its approachability, and our patterns in JavaScript should reflect this too. Vue’s documentation is undeniably superb.
    • Regardless of any framework decision, making educational resources available will be important
  • The role of corporate backing: Is Facebook’s investment in React a benefit in its supporting longevity of the project, or would it hold us hostage to the whim of their decision-making?
    • Vue is largely maintained by a single contributor (related: bus factor) funded via Patreon to work full-time on the project
    • It is not in Facebook’s interest to make large backwards-incompatible changes, because they too would suffer in their maintenance of hundreds of thousands of components across their products
  • On the complexity of React: is this more accurately attributed to supporting tooling? Specifically build tools like Webpack, and patterns for state management like Redux. For better or worse, React is largely unopinionated on architecture not affecting view rendering.
    • Would we need similar tooling for Vue? Both Vue and React offer no-tooling-required options, but both also push developers toward a build process (single file components for Vue, JSX for React)
    • Is build configuration something that we’d expose to developers anyways? Maybe not for the configuration itself, but a build process generally limits ability to directly modify files on a remote server.
    • Build tooling could be a worthwhile inevitably for developers to learn
  • Readability: Vue components may be more readable for new developers because they leverage HTML-like elements and attributes
  • Approachability: Ease of getting started can be a double-edged sword if it fails to teach fundamentals of the language that would be necessary for continued maintenance. The demands of rich interfaces necessitate a deep understanding of the language.
    • At the same time, we must not ignore that WordPress would not be where it is today if not for its ease of getting started. If we achieve maintainability but nobody is willing or capable to maintain it, then nothing is accomplished.
  • To differing sentiments between the developer chat and resulting commentary on last week’s summary: there are clear React leanings observed in the Slack chat, whereas the summary comments largely favored Vue.
    • How can we disassemble surface-level claims of “complex” and “simple” into a detailed understanding of why these feelings exist?
  • The broad impact of choosing a framework: Plugin and theme authors should have the freedom and flexibility to choose their desired tool.
    • In this framing, it should primarily be a decision of core contributors to make if it is they who are to be affected.
    • But is a framework decision going to count as a vote of confidence and unnecessarily skew perceptions one way or the other to choosing the best tool for the job?
  • Learning from the past: Why does Media Library see so few contributions? What lessons can we learn from this to avoid having this conversation again in a few years time, or is that an inevitability?
  • Future compatibility: Templating languages tend to have short lifespans. An example was raised of a Vue 2.0 breaking change regarding v-for as evidence suggesting that deviations from the core language are subject to change and therefore undermine stability. Learning the syntax of a language can be simple at the cost of understanding the underlying flow of data.
  • Process for adoption: A rewrite is unfeasible, and therefore modularity is an important consideration. Do we see the future dashboard as a collection of small applications, or a monolithic single-page application? There appear to be differing opinions on this.
    • Instead of rushing to adopt a new framework, where can we find ways to reduce our footprint, especially in light of revised browser support?

Conclusion and Action Items

With WordCamp Europe quickly approaching and this conversation having encompassed two JavaScript chats, it’s expected that a review of the discussions and formulation of action items should take place during the WCEU contributor day and at the Community Summit.

The topic of next week’s JavaScript chat will not focus on this decision, but you are encouraged to leave your comments below relating to this week’s topic or a suggestion for next week.

#javascript, #summary

JavaScript Chat Agenda for May 30th

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

  • A continuation of last week’s discussion about a framework for future WordPress JavaScript.
  • Open floor

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, #javascript