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

JavaScript Chat Summary for May 23rd

Below is a summary of the discussion from yesterday’s JavaScript chat (agenda):

Introducing a JS module pattern to WordPress

@omarreiss helped lead the discussion and kick-started the conversation by opening a detailed and thoughtful ticket in trac (#40834) which introduces modules, their goals and how we could go about using them in core. The discussion was around considerations specific to WordPress and a need for modularity was mentioned – @westonruter called out this need for the Customizer,  see #30277. Ideas for code that could be extracted into modules included quickedit, core date utilities and wp.media.view.FocusManager.

The decision was made to move in the direction of using Webpack (and ES6 imports) as our bundler of choice, and to work first on switching out browserfy in our current build chain.

Choosing a future JavaScript framework

Discussion started on choosing a new framework for use in core. The main frameworks discussed so far were React and Vue. Attendees shared their hope, goals and criteria for choosing a new framework and mentioned: stability, longevity, mature, well-adopted, proven in a WordPress context, accommodating to accessibility requirements, interoperability with existing code, architected to support predictable data flows and composability, alignment with efforts like Calypso,  composable, extensible, testable and ease of developer adoption.

@kopepasah promoted Vue.js, saying he found it “much more approachable and highly extensible” and also “Vue single file component is amazingly organized and easy bundle and build.” See https://vuejs.org/v2/guide/single-file-components.html.

@rmccue pointed out that the React core development philosophies match up to ours quite well: https://facebook.github.io/react/contributing/design-principles.html

@afercia raised accessibility and wanted to know which framework was best suited to offer support, specifically in handling cases where direct DOM access and manipulation is needed.

@aduth shared the reasoning behind the choice of React for the Gutenberg project: https://github.com/WordPress/gutenberg/tree/master/element#why-react

As anticipated, the decision was not settled in the meeting and discussion will resume in next week’s meeting. Currently, React appears to be the favored candidate. Please add to the conversation in the comments below, and join us for further discussion at our next meeting, scheduled for May 30, 2017 at 13:00 UTC

For the full meeting notes, see the Slack logs.

#javascript, #summary

JavaScript Chat Agenda for May 23rd

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

  • Introducing a module pattern for WordPress JavaScript, see #40834.
  • A framework for future WordPress JavaScript. What are the goals and criteria for making a decision, and what do we hope to get out of it? To specific frameworks, which options are we considering, and who can share their experiences in implementing them in the context of WordPress? Finally, how do we make decisions about ongoing development and maintenance of existing Backbone-based features? Note: this discussion item may take more than one meeting.
  • 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

JavaScript Chat Summary for May 16th

Below is a summary of the conversation from today’s JavaScript Chat (agenda, Slack archive):

Build Tools for Code Standards

  • There’s a desire to replace the current JSHint configuration with an ESLint solution (#31823)
  • @netweb shared a number of ESLint-related projects targeting parity with existing JSHint and JSCS configuration
  • JSHint was mainly designed to identify potentially erroneous code. ESLint builds upon this with support for style and custom rule enforcement
  • What steps do we then take to extend the ruleset to meet the remainder of the JavaScript Coding Standards? Parity with .jshintrc has the benefit of serving as a drop-in replacement, but legacy code and existing patches may be impacted by broader rule enforcement.
  • Options for incremental adoption of rules: first configure rules as warnings, or attempt to lint only lines modified in proposed change (as in PHPCS, or Calypso’s git-based eslines)
  • Alternatively, forgo incremental adoption and instead make a single pass to fix offending code, using ESLint’s fixer or prettier (discussion ticket to be created), at the cost of potential disruption to existing patches by conflicts introduced. This appears to be the favored path.
  • How do we reconcile a desire to retroactively fix coding offenses with our guidelines explicitly forbidding this sort of refactoring? The guideline was revised with an ending note about internal consistency. @jorbin later remarked that exceptions have been made in the past for allowing JSHint-based refactoring.

General Remarks on JavaScript Standards

  • @aduth raised a concern of the difficulty in following spacing exceptions on function arguments, arguing that the mental overhead in understanding how context varies application of the rule could explain why it’s followed inconsistently.

Tickets

  • @adamsilverstein requested feedback on a ticket proposing to make two utility functions specific to Press This more widely available (#40635)

Open Discussion

  • A meeting topic was proposed: Module patterns to extend or replace Browserify and make internal utilities more broadly available. Special attention will need to be made for interoperability with existing patterns for declaring script dependencies.
  • A meeting topic was proposed: Making a decision on a framework to use in place of Backbone, based on consensus from last week that a replacement is needed.

#javascript, #summary

JavaScript Chat Agenda for May 16th

Join us for our weekly JavaScript Chat on May 16, 2017 at 13:00 UTC, where we will discuss:

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

JavaScript chat summary for May 9th

The focus of the meeting was reflecting on ongoing and past efforts to apply JavaScript more heavily in WordPress, to help inform requirements of the tools we’ll need to implement the features we want to build.

To the end of better understanding what we have in core now, @adamsilverstein shared some research he is working on: A slidesdeck of JavaScript added to each version of WordPress (click the right arrow on the first link to go thru the versions) and a summary of features that use JavaScript added to each version

Next, we delved into the pains, tools, patterns, etc. used in the following ongoing efforts:

  • Porting the media library and TinyMCE into the Customizer with Media and Text widgets
  • Creating new and revised UIs leveraging the REST API like Quick Drafts and New List Table

@timmyc talked about his experiences developing the new Media Widgets, which are all built utilizing wp.media. @westonruter has created a great summary of some of the bumps they had along the way.

@youknowriad shared the experience working on the editor project using React. He said the main pain point is making TinyMCE work in a “controlled” way (unidirectional data-flow).

@rmccue and the REST API team have been looking at making the dashboard use the REST API generally, looking at a lot of the core JS. He summarized “WordPress has a JavaScript framework already: we have all the pieces that you’d have in a framework, but they’re not tied together, and they’re very poorly documented… Additionally, every piece is subtly different in architecture, implementation, design, etc.”

@joemcgill added the overall architecture of wp.media is not well documented anywhere, so there’s a huge barrier to entry for anyone who wants to work on even minor bugs. It’s not simply understanding backbone, but you also have to understand how wp.media has implemented a custom frame/region/state model.

The team agreed to work on documenting the overall wp.media architecture, and @omar offered to try to focus the team at Yoast on helping with documenting wp.media as part of their ongoing effort to document core JavaScript.

Discussion continued around the reason developers find working with media and other core JS so difficult. Is it the complexity? The lack of documentation? Or is the architecture itself the problem? Probably all of the above.

The discussion touched on the history and evolution of our use of JavaScript in core, and the consensus was that moving forward, new view/UI components should be built in a more modern framework such as React or Vue. The specific framework is a conversation for another day, the decision was that we need something new to be able to achieve the experiences we want to build. At the same time, we need to maintain what we have and ensure developers can use it. There was some discussion of core documentation and a proposal to add JSHint to core’s build process.

Discussion continued to backward compatibility, and the issue of “losing” PHP hooks when we switch old functionality from wp-ajax to the REST API. Do we need to provide backward compatibility for all PHP hooks? Or can we offer new approaches for developers to extend WordPress, for example, wp.hooks?  @omar shared their experience at Yoast when they switched their content analysis from php to js.

The meeting wrapped up with ideas for next week’s meeting the team made a plan to discuss modularity/modules as well as JavaScript coding standards.

As a reminder to contributors that there are over 300 open tickets in the JS focus that can use your help!

For a full transcript of the meeting, check the slack logs.

#javascript

JavaScript Chat Agenda for May 9th

Join us for our weekly JavaScript Chat on May 9, 2017 at 13:00 UTC, where we will discuss:

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