Weston Ruter 5:19 pm on August 23, 2023
Tags: gutenberg, ,   

Community Summit Discussion Notes: Addressing backwards compatibility in Gutenberg

From the schedule session:

This discussion aims to explore the challenge of backwards compatibility in JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. and PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php. APIs from the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ project into WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. Currently, there is little clarity around maintenance of backward compatibility across the project, resulting in confusion for developers and performance issues. There are two focus areas:

  1. Depreciating officially stable APIs that have been replaced
  2. Depreciating unstable, experimental, or internal APIs that have been shipped in WordPress.

Perspectives needed: Senior WordPress Core contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org./committers with deep knowledge of past lessons learned around backwards compatibility, Gutenberg contributors with working knowledge around processes and decision making.

Facilitator: Marius L. J. (@clorith)

Notetaker 1: Weston Ruter (@westonruter)

Notetaker 2: K. Adam White (@kadamwhite)

Raw Notes:

  • Deprecation is always OK. The problem is not deprecating and replacing them with new ones. The problem is with removal of the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. entirely. Is there anyone who thinks things should never be deprecated?
  • Are we willing to maintain something forever?
  • How can we ensure that nothing breaks for the user and help people through the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. process?
  • Performance issues that we need to consider. WordPress is becoming bootstrapper for deprecated.php. We’re dealing with people’s websites, and we can’t break them. White screen of death is a problem.
  • We have a tool in Gutenberg called log-deprecated-notices, which helps with visibility for deprecations that users often don’t see in the console.
  • What are the specific use cases or problems that we’re trying to solve?
    • wp.nux was deprecated
    • script was removed and then restored to fix the syncing script
    • Converted (or intend to convert?) method to a noop function to avoid errors without impacting behavior
    • ServerSideRender was moved to its own package and shim was removed in a version, and this caused problems with GravityForms extension that used the old API. 
    • Breakage burden is that Gutenberg moves much faster so it’s a higher level of effort for agencies and pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party authors, upgrading WP out of sync with plugins can cause errors or at minimum generate many warnings
    • Clients often say that they don’t want to update plugins at all, for example when blockquote blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. was enhanced to allow embedded rich text (as it broke editorial flow/”looked different”). So it’s more than just deprecation issues. It’s also an issue of new features being added, or visual appearance / UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it. of existing features changing.
  • Plugins don’t auto-update whereas core does. Can’t rely on them updating the tested-up-to or minimum version.
  • Issue with default themes and patterns: when updating to use new scheme, breaks compatibility with the original version of WP for which the theme was released. Some themes have patterns that don’t transform, a forward-compatibility break. So we need to think of both back-compat and forward-compat.
    • Pattern directory is going to have versioned patterns, to serve the appropriate pattern to the specific themes. 
    • Themes that have built-in patterns need to be updated to use the pattern directory.
  • Markup changes alone can cause problems. For example, a selector was more specific than it needed to be (e.g. internal div wrappers), which broke styling. 
  • Changes to padding in block.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. has caused problems. Enterprise needs to remove certain editorial controls, and changes to class names in sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. controls breaks this.
  • Are patch versions possible for themes? 
  • Versioning of themes adds a heavy maintenance burden to keep old themes updated to be compatible with the latest versions of WordPress.
  • Community members who build themes in very surprising ways in production. We need to make sure that we’re mitigating risk of people using template files in a very strange way.
  • How does this affect security? How many versions are we supporting? Are we going to have to backport security updates to themes? Is this even possible? Currently we backport to WordPress 4.1. Ideally, officially WordPress only supports current version minus one, but this isn’t reality. We need to progressively move toward supporting fewer versions for sustainability.
  • What happens when we change the styles of blocks? What do we do with old existing content? Deprecation routines require editing a post in the editor.
    • There are buckets such as what changes are required to be communicated to users versus developers versus site owners. We’ll need to communicate differently.
  • For behavior changes versus errors, if we have blocks in WordPress core people can reuse these core blocks. Extending blocks is a bad idea however because since they change, as an agency, we avoid relying on core blocks by forking a core block to avoid the risk of breakage. There’s not a mechanism to evolve over time. WordPress used to work for everyone across versions, but it doesn’t work anymore for JS or content stored in the DB. There should be versioned blocks and abstraction for the building blocks. Having a fatal error is bad, but it is just as bad to have a fatal error in database content.
    • For reusing core blocks, it may involve adding a property or adding a switch. It could be adapting user interface. Otherwise, user interface may stay the same, but markup could be very different. The way you extend a core block, it is very tightly coupled to the implementation. A minor change to a core block could break all extensions. Because of this, internal best practices at agency is to not extend core blocks but to fork. Additionally, there are lacking extensibility to change user interface, hiding controls, etc.
    • Another agency decided to extend core blocks by using inner blocks, wrapping the core blocks. But any change to the core blocks broke back-compat.
    • Yet another agency uses JS and PHP filters to add the desired control and HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. attribute. Works in most cases. But classnames and selectors are not stable. Breaks customization. Especially because client side code (sidebar in particular) doesn’t provide the level of filterability that developers are used to in PHP
  • Is there any existing effective solution for applying block deprecations across a site? There is a 10up plugin.
  • When content breakages happen, it isn’t apparent when updating a plugin or core, it can be realized much  later when they try editing a post.
    • Sometimes that will change the frontend experience immediately, other times not until they open the post, other times won’t change frontend at all but post becomes ineditable.
    • Could there be a WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ command that scans posts for potential problems
  • WordPress doesn’t have public definition of backwards-compatibility. User trust is the goal. We want users to update to use the latest version of WP with confidence that their sites will continue to work. Do we need a more strict definition of deprecation? Removing myhacks.php broke Matt Mullenweg and Mike Little’s sites. Ideally we could remove far-deprecated APIs; there have been PHP functions which have been deprecated since 0.7. PHP functions don’t really hurt TTFB, but adding more JS functions does hurt performance. It may not be a reasonable expectation that a plugin written for a specific version of WP that it works forever.
  • Expectations are important. It impacts trust. It’s fine if things break if we expect them to break. It’s worse if something breaks unexpectedly. We need to manage expectations. For back-compat, from software engineering perspective, if there is any change to an explicit public interfaces, that is back-compat break. The problem is that WordPress has a lot that is implicitly public. WP-CLI, for example, has a lot of internal integrations that can break with new WordPress updates, but these changes weren’t expected to be breaking. It might be time to generally re-think what the back-compat means for JS and database content.
  • Surprising that we don’t have backwards-compatibility policy. Important to document policy for communicating deprecation.
  • One reason WP is so popular is commitment to back-compat. But we’re failing right now.
  • For core blocks, there should be more APIs for managing UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. controls. In PHP there is one API surface, but in JS there are multiple avenues including CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site.. Quote block and list block was a major breaking change. Table block in the future will likely have the same issue.
  • The largest user base isn’t voiced, and that is people who are building their own site or paying someone to build a site for $1000. These are the “lower-case d developers” (aka implementors). After such sites are built, they’re expected to continue working after maintenance relationship ends. What communication plan can we have for sites that no longer have developers?
  • We may be looking at the past with rose colored glasses. Was there a time at which we were great at back-compat? New major versions of WP would cause fatals. Managed hosting and staging sites in part exist because of upgrades causing errors. Many of us have careers because of need to maintain sites. Having a clear definition of back-compat and user trust is important for ourselves. Historical perspective is important.
  • It’s very slow to change workflow and re-tool as WordPress changes.
  • Gutenberg team did a wholesale deprecation of class names in the editor. This was communicated fairly widely. Class names were kept for 2 years after deprecation. People still complained after removed. Difficult situation. With experiments, people like to tinker with internals. Using something marked as unstable, it should be expected that they are not to be relied upon. In the JS packages, there’s a way of hiding APIs via a mediator package that hides references to prevent people from using stuff. It’s working. Initially it was just hiding functions, but now it’s moved onto switches to functions. But we’ve somewhat bypassed the expectations from the community. Do we obfuscate all classes? Are we treating developers like children? Do we need different tiers of support?
  • For class names and styles, do we prefix class names to mark them as private? It doesn’t work for PHP functions.
  • There’s a difference between problems with code and problems with database content. If you work on a large WordPress installation, a code fix is easy. A content fix is hard. Deprecating a content change, there’s no clean way to fix a content issue in production. We haven’t figured out how to do that. If someone is doing something stupid, we shouldn’t support it. But in general with the way Gutenberg has evolved, we’ve seen new problems evolve for which there is no official or good solution, just various ways of pain. If the Table block has legacy issues at some point, we’ll also have legacy issues with all blocks. There are no guarantees with how the web will evolve. In the past, WP was good at evolving with code changes. But now the content is tied to the code which could get deprecated. 
  • Sad that plugins may not work for a decade in the future.
  • When we deprecate things, we do continue to support them (e.g. security fixes).
  • Class names being used for extensibility in the editor was due to there not being APIs. Gutenberg should be using the same API for its own controls, the same as plugins extend it. If it did, there would not be a need to resort to CSS hacks.
  • There’s a problem with “canonical posts” where people go to find a solution to a problem even when it is way out of date.
  • Plugins often try to support many versions of WordPress and Gutenberg. It seems we need a better way to check versioning.
  • On https://wordpress.org/about/security it says WordPress has a strong commitment to back-compatibility. 
  • We say WordPress is chosen because of its back-compat commitment, but most users probably wouldn’t include that in their top 3 reasons they use the software. We need to be mindful of how far we maintain back-compat, and be prudently-progressive so we don’t keep making our lives difficult. We should continue to push forward so it isn’t more complicated than it needs to be.
  • We’ve broken back-compat in every release, but it has been in small intentional ways. We’ve reached out to plugin authors in advance to make sure that they test and update their code.
  • Having layers of support could be a good path forward. How would this be communicated to the implementor/configurator site builder? They may not even know what “API” means, let alone “stable API”
  • There’s a block editor back-compat statement. It says that the DOM and CSS are not maintained for back-compat. The Learn WordPress project may help with getting users to read docs.
    • Gutenberg does also have a defined back compat stance. https://developer.wordpress.org/block-editor/contributors/code/backward-compatibility/
      • Explicitly says class names and DOM are not part of back compatibility. 5.2 change went above and beyond by outlining what was happening.
      • Can’t solve people not reading docs… but learn., and centralizing resources, does help
    • Experimental APIs, frequently developers expect that they will have more maintenance bandwidth than they actually do. Overconfidence that they’ll come back and fix things.
  • Implementors have had assumption that the theme built once will never break. When responsive previews were added, there was no way to customize controls when different device is selected. There are experimental APIs that have been marked as such for years. Developers want the UI to look consistent, but to do so they have to use unstable APIs.
    • JS components are in a very bad state right now.
  • For each release, there is a issue created which lists out all unstable APIs to ask whether they should be marked as stable. But they don’t get much engagement. But may get better?
  • Core does a lot of deprecations and _doing_it_wrong(). There’s no timeline for when to remove something. If we’re re-thinking the concept of back-compat, we should reconsider that. The back-compat statement said that the site will function but it won’t necessarily look the same (i.e. IE support deprecation).
  • What’s the social contract and expectations? There’s a large segment of our users who don’t have any awareness of our social contracts. A great thing about our ecosystem is you haven’t had to know them.
  • Back-compat is indeed not a reason people choose WordPress, but it’s probably because they haven’t had to consider it before.
  • We may need different back-compat statements for PHP vs JS.
  • We should have an understanding for the purpose of an API. We don’t know when an unstable API should be considered complete. If we had that defined, it would help subsequent developers know when to mark something as stable.
  • [Bio break]
  • Recap:
    • We would love more APIs
    • We would like more clarity on deprecation
    • We don’t have a single definition of back-compat; there are two definitions on back-compat on WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/. We need this going forward, a single one
    • User trust is important, the social contract for extensions. We need to be more explicit.
    • There would be some benefits to getting more explicit extension points in the editor. The implicit ones (class names, DOM elements) are getting used unintentionally.
    • There are several different user groups (developers, core contributors, implementors, site owners, users) 
  • Border control for blocks is still marked as experimental, but it feels pretty stable. But if you want it for your custom block, you’re going to use the experimental API and not reinvent the wheel. Do we include experimental APIs in our docs? Developer Blog is writing about these experimental docs, but calls them out. Consensus needed when to graduate to stable. Docs have various levels of being up to date. There are so many ways to develop with WordPress, and we need to show people the best practices. For example, developers are still enqueueing assets in old ways which are not ideal when using the editor. We can help extender community by improving docs.
  • Why did we adopt back-compat as a value for user trust? Are we chasing back-compat for back-compat sake? There’s a benefit. People don’t abandon WP due to things breaking. We’ve learned at how to anticipate back-compat problems. A new problem we have with Gutenberg is we made a philosophical decision to encode a lot more presentation into the content. Before Gutenberg, it was just simple markup (shortcodes notwithstanding). People want to create more visually-rich content. The presentation is part of the content, so it gets encoded with the content. This content can include inline CSS and hard-coded class names. Old sites would work around limitations with cowboy codingCowboy Coding This refers to making code changes on a live site rather than in a staging site. in classic editor that cannot transfer easily to a new theme. Large organizations can hire agencies to solve the problem. We’ve created a situation where interfaces create content that gets stuck in the database which needs to not break going forward. This is a challenge for maintenance and testing. Old versions of the blocks are stuck in a database somewhere. We need best practices.
  • Back-compat case study is iframed editor. We had to choose between quality of editor and quality of themes. The classic editor also had an iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser.. Iframe was abandoned in initial block editor, but it was a big headache for media query previews. Site editor needed much more styles, so it used iframe to sandbox styles. Iframed post editor is now implemented for block version 3. There are two experiences now, where if someone uses block version 2 a non-iframe version. It’s difficult to search for plugins using block version 2. There are also a lot of custom block development by agencies or premium themes. Difficult to communicate.
    • We’ve observed that users have a higher expectation for quality from premium themes and plugins, although they’re the most difficult for us to reach out to in order to fix compat.
  • There should be acceptance criteria defined for unstable APIs. Once all met, a quick check can make them stable.
  • Regarding deprecations and breakage of back-compat, we need to account for site owners and users. We could keep track of deprecations and experimental unstable APIs to then surface in Site Health. With every update of WordPress core, the site health score could decrease if the deprecations and unstable APIs aren’t addressed. We’ve done something similar in the past with the fatal error protection. We tracked fatal errors and stored them in the DB and bypassed loading offending files and showed the errors to the user without causing a fatal.
    • Could we do client-side inspection of stylesheets and scripts to flag usage of things. These can be logged to the console, but that’s meaningless for many use cases. It could get surfaced in Site Health.
  • Regarding the definition of done, developer relations can’t wait for it to be stable before it gets shared with the world. We need usage to validate the design. There is a gap between technical and non-technical: how do we bridge the gap? Do we need someone who is shepherding the process? Product owner? Maintainer role? There could be a living doc that always has the current status made clear. Also, the product development lifecycle can have it documented how deprecation happens.
  • It’s not reasonable to expect people to not use experimental APIs. We should have defined guidelines about what something is. 
  • Everything in Gutenberg currently goes into TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. as the Editor component or maybe Widgets. We should be more fine-grained and make it clear who the owners are.
  • Is there any official timeline for experimental APIs? No. But there should be.
    • There is a human problem with commitment. Gutenberg is a safety net. People are comfortable having an experimental API and it’s too easy to continue that way. There are no accountability processes of taking the uncomfortable step to commit to fixing it in the future. It’s an emotional problem.
  • Maybe we should have more stages than just experimental and stable, like on the web platform.
    • Unstable is supposed to be wild west with no guarantees. Also used for internal.
    • Experimental is intended to be the more stable than unstable.
    • Stable
    • TC39 has proposal system. For example, a babel transform has to be available for a given stage. Node also has a model, where zero is something is extremely experimental which will break all the way up to 4 being final not breaking, and 5 is deprecated.
  • Should core not allow upgrading if plugins aren’t marked as being compatible? No.
  • There are different degrees of backwards-compatibility breakage. An editor breakage is less bad than a frontend content breakage. A JS error is less bad than a PHP fatal error.
  • ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. class names in the editor are not stable.
  • Regarding data integrity and markup/CSS being tied to a block, the early design considerations revolved around integrity. Gutenberg initially had to thought about case where plugin is deactivated, and it had to be compatible with old sites using post_content. Data integrity of content is more important than aesthetics.
  • Catching deprecations is easy, but there will be a gray area for introspection on private APIs. How do you catch calls to things that shouldn’t have been called in the first place?
  • Logging deprecations in Site Health should be hacked on during contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/..
  • WordPress takes on technical debt so that users don’t have to. Our lives might be harder or more difficult, but we do so for the sake of the users. Are we doing something for ourselves or the users?
  • Should the Gutenberg plugin be the only way you can access experimental things? Should that be part of the social contract? Plugin dependencies could play a role.
  • Should we not allow experimental in theme.json and block.json? Should it be that the version changes are done instead? Could make it easier to surface changes and be made aware of themes/plugins that are only using old versions of these schemas.
  • Gutenberg plugin can indeed be the wild west with experimental APIs being available, as it is betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. software. It is a more relaxed attitude. How do we publicize and notify users and developers? Is Make Core adequate for comms? End users do not read these. But we can surface them in Site Health with logging of the deprecated API usage. What about the pushback against telemetry?
  • The Link control has been marked as experimental for years. 
  • How do we do developer relations with premium plugin developers? Should developer relations get licenses for premium plugins so they can search through source code for code that needs to be changed? The same goes for reaching out to agencies who develop custom code. Is FFtF an avenue for reaching out?
  • How do experimental APIs relate to prefixed CSS on the web platform? The requirement to have Gutenberg plugin to be active could be similar to new browser model of having flags enabled.
  • We could monkeypatch unstable/experimental APIs to log out usages.
  • It would be nice if deprecation notices in console linked off to documentation for what should be done instead. It should say when the depreciation was introduced in WordPress core and Gutenberg.
  • For someone who is not a day-to-day contributor to core or Gutenberg, the roundup posts for Gutenberg changes and core changes aren’t very helpful. They could be made more thematic. Dev notes do exist, but they could be made more helpful.
  • There is way too much going on with Make Core. The new developer blog is more oriented toward teaching. How do we not cause confusion with users? Communicating developer changes to end users (e.g. via WP Tavern) can be confusing and concerning.
  • Simply degrading a site score in Site Health isn’t great because it is not actionable. There was a Site Health test for usages of jQuery Migrate which flagged the plugin that was using it, so they can put pressure on the plugin author. The same should be done for deprecation logging.
  • There can be stages for the experimental APIs. The private APIs get marked as experimental as a hack. 
  • Gutenberg allows for experimental that core doesn’t. If we stop exposing experimental prefix, and instead document the stage for a given API. What do we do about existing experimental APIs? If they have remained for a few releases, they can just be made stable. When something is getting logged as deprecated due to a different name, fine: it still works. We don’t want to ruin developers’ days. We should be more pragmatic about deprecations.
  • Core has recently been using more private APIs that aren’t able to be extended upon, just done for the sake of Gutenberg.
  • For a good back-compat strategy, we also need to consider forward-compat strategy. For example, adding responsive attributes to images was forward-compatible.
  • The WordPress developer blog is a dotorg resource outside of Make, and it is an avenue we can use to communicate.
  • Idea to get visibility and communicate with premium theme/plugin developers, provide way for them to submit their code to store in a secure location.
  • We don’t have a consensus yet around expectations around the product we want to keep in motion. There are big things we want to do which hopefully will be as stable as everything currently in WP. Users get ticked off when things change, even slightly. We need to keep pushing, there’s no other way around it. What can we do to make it easier on users?
  • Proposal to have breakout session how to communicate breaking changes.
  • Themes
    • Properly define what backwards compatibility is
    • Set timelines for stabilizing features or functions
    • Have some grouping of impacted users, due to deprecations.
    • If we add more APIs, be more familiar with hurdles implementors need to work through. Do more dogfooding.
Alternative version of raw notes (some of which have been incorporated above)
  • deprecation should always be OK. The issue is in the removal of deprecated things, that’s where breakage occurs.
  • What are better ways we can push people in the JS world towards what they should do?
  • Also need to talk about performance issues. We’ve traditionally been strong in back compat, but there are performance issues in terms of JS which impacts client side performance; PHP APIs that impact TTFB on server. WordPress is slowly becoming a bootstrapper for deprecated.php.
    • We’re dealing with people’s websites and content.
    • If an update causes a WSOD, that’s a problem
  • We do have a tool which hasn’t been used lately in gutenberg, called Log Deprecated Notices. Could be transferred to the wp org.
  • Are there concrete examples of this being an issue?
    • Recently there was a deprected package that wasn’t used by core (nux)
      • Package deletion was reverted in RC1 so that syncing script works again
    • Plugins which use Gutenberg aren’t updated in sync, can yield tons of notices when upgrading WP or even break it if the plugin hasn’t been updated in a while.
      • Plugins don’t update, where core does.
  • Counterpoint: things break for the user even if code is working as intended. Clients don’t like UX changing
  • Issue encountered with default themes and patterns: Said, let’s update default patterns in themes to be the new syntax. When it got committed, realized it wouldn’t work, because if a default theme was released with 5.0, it needs to work back to 5.0. new syntax won’t work on old versions of WP.
    • Need upgrade paths, some themes have patterns that don’t correctly transform to new block editor state. That’s a BC break, in the sense thst it doesn’t work for user — but it’s really a problem with forward compatibility, because the way it was built is not capable of being migrated forward.
  • Going back to point about things that break, even markup changes cause problems. Selectors were more specific than needed, so it caused unexpecred changes
    • Another example, class names change release to release and then CSS targeting for custom code breaks
  • Can themes declare what version of WP or PHP they can support?
    • Yes but default themes are supposed to go back to their original release version.
    • We have this capability with plugins, to say v1.7 is good up through wp 6.2, but themes do not have that capability
    • Would prefer to ensure there’s always a path to update
  • Did a lot of conversations with community members about how they were building themes. Got some very surprising responses, about things that people were doing in production. Not ways we ever expected for features to be used.
    • Need to somehow mitigate risk of using template files in a strange and unusual way.
  • Security: The more complex our compatibility model, the harder backports become. We backport to 4.1.
  • Need to work towards supporting fewer versions, or maintenance version becomes more untenable than it is now.
  • Deprecations require you to visit a page. Any thoughts about how to handle style or markup changes to old blocks?
    • There are buckets and audiences. What changes do we need to communicate to an end user, theme developer, plugin developer, site owner, all of the above.
    • What we’ve noticed around changes, there was this promise that if we have these blocks in WP core that they will be building blocks, and people will use and extend those rather than rebuilding.
      • The extension in practice is a very bad idea, because the way blocks evolve and change over times makes it so that you cannot rely on what you will have after you build it.
      • As an agency, we try to avoid depending on core blocks, would rather fork and make our own version of core blocks rather than extending core blocks because they can break with any update.
      • While it is bad to have a fatal error in your code, it is worse to have a fatal error in your DB that impacts 10k posts.
    • Q: Is there any effective existing solution to bulk processing of block deprecations?
      • 10up has a plugin
    • Frequently, when something breaks it’s not immediately apparent because they won’t know until they open a certain post in the editor. Sometimes that will change the frontend experience immediately, other times not until they open the post, other times won’t change frontend at all but post becomes ineditable.
    • What was meant by “extending core blocks,” what apis or goals was that referring to?
      • Might want to add a property which the client wants to see, one more switch to cause a behavior change. Other times it’s a combination of adapting the user interface.
  • Several people have mentioned backwards compatibility. WP has no official statement. There are 19 people in this room, we probably have 25 definitions of what back compat means here.
    • Ultimately what we mean is “user trust,” users should trust that they can update and their site can continue to work. Maybe we need a more strict public definition of what we mean by backwards compatibility.
  • Extending core blocks: wanted to use core first, but didn’t want to fork. Chose to use wrapper blocks and innerblocks, but when something updates, changes to style and class
    • Adding width controls to blocks, adding behavior like to add a lightbox modal to images. Use editor.blockEdit filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. is common in certain environments.
    • While things DO break, Filtering core blocks is the only effective way to roll behavior out across an entire site.
    • CSS selectors are part of Gutenberg’s public API
      • Especially because client side code (sidebar in particular) doesn’t provide the level of filterability that developers are used to in PHP
  • Expectations have an impact on trust. It’s fine if things break if you expect them to break.
    • From software engineering perspective, would be good to have explicit public interfaces which don’t change (remove or be modified) without an alert. What gets complicated in WP is we don’t have explicitly defined public interfaces. The implicit public interface is the entire code.
    • Way gutenberg is evolving, so JS and client-side heavy, things are stored in DB… it might be time to rethink approach to backwards compatibility. In one dev’s opinion, what we did in the past does not work now
  • Largest userbase are implementers, not “WordPress Developers” the way this room thinks of that. Build a site, cheaply, then leave it with the site owner. Those losers get lost in the upgrade path, “why didn’t your dev change it for you,” well, they don’t have a developer.
  • Are we looking back on the past with rose-colored glasses? Thinking that we used to be great at BC?
    • It’s not too long ago that every time there was a major releaseMajor Release A set of releases or versions having the same major version number may be collectively referred to as “X.Y” -- for example version 5.2.x to refer to versions 5.2, 5.2.1, and all other versions in the 5.2. (five dot two dot) branch of that software. Major Releases often are the introduction of new major features and functionality. of WP, plugins would widely fatal. That’s part of why managed hosting exists, and staging sites became necessary, however hard they were to manage.
    • Having a clear definiton of back compat, our philosophies, being clear with ourselves, will help us deliver better service to the Internet.
  • Thinking about how we train long tail of developers in the world to take the path we see as “correct,” how we communicate that, if the information is easy to find — saying source code is source of truth still leaves things up to interpretation.
    • In agencies and freelance alike, you build habits and workflows, and it’s hard to retool as things change
  • Had a wholesale change of classnames in 5.2, felt like it was communicated widely. Kept the classnames a year after the deprecation deadline. In total it was 2y of deprecation, and even then, when they were removed, many people complained.
    • Also ties into experimental APIs. People like to tinker with internals, but then, what is the social contract that is implicit? Many devs will use something that says experimental, and feel they are using it at their own risk and discretion.
    • Block editor is experimenting with a private mechanism of hiding things, with a mediator package that buries references to prevent external developers to use things that are in flux. It’s working, and block editor has been expanding on how it’s used, but now it’s also hiding some arguments or switches in internal functions that do get exposed.
    • All of this works, and in a way we’ve fixed one of those big problems in how things went down in the JS world. But have bypassed the social question around expectations. We’ve been treating people like children, “you can’t have the toy.”
    • Similarly, if you could obfuscate classes… would help Gutenberg, but reduce customizability
    • Opinion: We should have multiple tiers of support. Might go a bit out of our way to be gentle about some of the internals, to give people extra time. But don’t support it same way as “official” things.
  • Is there any chance with classnames and styles issue, that can be deliberate about chage, “this is presentational for the editor,” prefixing…? half-baked idea
    • Goal was to have styles be same in editor and frontend, though
    • (styles that break are often in the sidebar / gutenberg controls)
  • There are problems with code, and problems with what you store in the DB. If you do a lot of WP installations, you may need to work for weeks to migrate content to new versions to get rid of problems in the DB.
    • In the past WP did a good job of giving you ownership over your content, and let it remain stable over time as capabilities grow. But now content is more tightly tied to code. You will need to do costly migrations, or start from scratch.
  • A few comments: A little sad that we won’t have plugins that work for a decade. The fact that 10yo code still works makes one dev in the room proud.
    • Do we support deprecated things from security stance? Yes, within reason.
  • Comment on the classname thing: people extending editor: that comes out of a lack of extensibility in editor. Gutenberg game in with attitude of not wanting to offer extensibility because of it creating a poor UX. But people expect to modify things, and want to modify the sidebar.
    • If gutenberg had more explicit extension APIs, might run into fewer IMPLICIT api usage issues.
  • Canonical posts: WP documentation is distributed. If you google “add defer to post,” Google sends you to outdated information.
  • It’s very challenging for plugin developers to figure out how to support multiple versions. They’ll try to support many, and in doing that in Gutenberg, they need to do version checks. Need a better way for plugins to do the right thing in their current version.
  • WordPress core has a back compat statement on /about/security
    • But, would challenge that WP is chosen because of commitment to back compat. Think it’s something we do out of care for users, but assuming we continue to have a care for back compat and for users, and the safety of their sites and content, we need to be mindful about how far we maintain back compat.
    • Need to be prudently aggressive at moving that upwards, to avoid the BC maintenance burden be unsustainable.
  • For many, many years, every release breaks BC in some form. Usually intentionally, usually in small ways, and with reaching out to people where we know code will break.
    • Shiny updates, (4.2?), we specifically changed action orders. Reached out to plugin authors that were using both actions.
    • Depends on WP plugin directory. Hard to reach out to paid plugins sometimes, and paid plugins may have increased user expectations.
  • Layers of support: that might be a good path forward. Big question, how would we communicate that to the person who has an implementor building their site. How do you know that you have a site which doesn’t use experimental APIs and explain what that means?
  • Gutenberg does also have a defined back compat stance. https://developer.wordpress.org/block-editor/contributors/code/backward-compatibility/
    • Explicitly says class names and DOM are not part of back compatibility.
    • 5.2 change went above and beyond by outlining that.
    • Can’t solve people not reading docs… maybe learn.wordpress can help centralize canonical information, rather than leave it spread across csstricks and a million other sites?
  • Experimental APIs, frequently developers expect that they will have more maintenance bandwidth than they actually do. Overconfidence that they’ll come back and fix things.
    • One of the reasons that we hear from block plugin authors, when we added responsive preview sizes, for a long time — maybe even still — the selector to determine what mode editor was in, was marked as experimental. No way to change controls in a different mode.
    • When adding controls in sidebar, you have to use a lot of experimental components to use the same movable tabs, etc. Many of those controls have been experimental for years. Doesn’t feel like there’s a path for users to keep up.
  • Before each release, G creates a big issue, outlining experimental APIs and asking if they should become stable. Experience over last 7 releases is that nobody responds.
    • Started pinging folks who worked on recent releases. Hopefully will get responses.
    • One of the topics we want to solve is how to handle deprecating experimental APIs once they become stable.
    • But yes, you do get tied to using experimental APIs to mirror how core does things. (JS components are in a very bad state.)
  • If we are rethinking BC, should we consider what it means to deprecate, in terms of when it will actually be removed?
  • On the /about/security statement, it says the site will FUNCTION. For IE, we don’t expect it to look the same. Do need a more proper definition.
    • “Function” will mean different things to different people.
  • Agree that BC may not be a front-of-mind choice for people to choose WP, but possibly because they’ve never encountered a break. Won’t think about it unless something does stop working.
  • May need different BC statements in JS vs PHP.
  • One thing that’s difficult when looking at the codebase, is understanding what the purpose of a package or API was — and when it is “complete.” back in the day when we were following feature plugins there’d be a kickoff problem statement, goals post defining what was trying to be solved. I find that there’s very few equivalent posts for an API that is being created. Therefore hard to know when something is “complete” and may be able to be considered not experimental.

(Break)

  • Recap
    • We would like more APIs
    • We don’t have a single, clear definition of what Backwards Compatibility means for WordPress.
    • User trust is important, and there is a social contract for expectations about how WP can be extended. Need to be explicit to reduce surprises for users.
    • There would be benefits to getting more explicit extension points inside the editor (sidebar was called out in particular). The implicit extension points get used where and when not intended, and that makes it harder to change them without breakage.
    • There are several different user groups (developers, core contributors, implementors, site owners, users)
  • Border control feels pretty stable. You’re going to use that experimental component if you want borders, because it exists and you don’t want to build your own. Tension between including experimental tools in documentation and tutorials because they feel stable — that’s something that’s been run into on the WP developer blog. Call out experimental APIs explicitly when they mention them. But plugin devs use experimental APIs extensively, really want to see a more consolidated effort to stabilize some of those APIs.
  • Education: documentation on .org, the block editor handbook is a lot of content. Some is out of date. But we need to be opinionated on how we present information — there are SO MANY different ways to build on WP, especially in JS.
    • We have iframe’d the editor in 6.3, and developers are using ways of enqueuing assets that was not recommended, but worked. And now iframe causes so many issues.
  • When we talk about user trust, need to think about why we adopted this value of BC in the first place, why it was useful to us. Don’t want to chase BC for BC’s sake, there is a benefit to us as a project and to our users.
    • Being able to avoid situations where users have to take many or complex actions to upgrade their site, reduces moments when users reconsider their CMS choice. BC has lowered the long-term maintenance cost of WP versus competitors.
    • We made a philosophical change in Gutenberg to encode a lot more presentation into the content. Prior to gutenberg, it’s paragraphs, images, headings. That limitation was a kind of strength but also achilles heel, we knew people wanted to create more visually rich content. So, presentation is now considered a part of the content, and is in the DB.
      • There are still places where we’re putting styles or presentational classes into the markup, it’s not all separated between style and content.
      • Those who’ve worked on larger sites with long histories of content, particularly older WP sites, you’ll have lots of folks working around limitations by cowboy-coding in the editor, putting divs and CSS into content. That solved an immediate problem years ago but now that content cannot transfer to a new theme.
      • Large organizations can pay agencies to solve those problems, or ignore them. But, we’ve created a sitaution where we need to be mindful not just of public APIs that devs use, but also that our interfaces created content that gets stuck in the DB, which we want to make sure still shows up properly on the frontend years later.
      • That challenge is more difficult both from a maintenance standpoint and also a testing point of view.
  • One case-study for back compat, is the iframing. We didn’t iframe from the beginning, so at some point needed to choose between improving the quality of the editor styling, or quality of integrating theme styles into the editor.
    • classic editor was also isolated. Nicely isolated, nice-olated.
    • media query preview was very hard initial non-iframe block editor
    • Have looked through directory for plugins with blocks not working in the iframe, but it’s hard to search for it because it’s usually handled with CSS selectors. And then paid plugins and agencies may not turn up, and there’s not an easy way to handle that outreach communication.
    • Users of WP may have a higher expectation of quality from plugins they pay for or agency work they pay for, so the fact that it’s hard to dissiminate information through that community is a particular challenge
  • Should have acceptance criteria for stabilizing experimental APIs. Once all are met, can quickly check and decide to make stable.
  • Need to solve technical deprecation issues in a way where non-technical users can participate in resolving them. Can you surface unstable APIs in site health component? If we can track that behind the scenes without impacting performance too much, could lead to a scenario where with every update to WP core, if no dev jumps in to fix deprecations, the count will go up and site health will go down.
    • Will site owners understand that it’s plugin code that’s dragging them down, or perceive that WordPress itself is getting worse? Need to choose language and presentation carefully.
  • We were talking about the trouble of Definition of Done. When do we call an API stable.
    • DevRel (learn.wordpress, etc) can’t wait for it to be stable before it gets shared, people need to start using features for them to be successful.
  • Gap between technical and non-technical
    • Thinking of product development lifecycle, somebody shepherds the process — maintaining the communication around it, aligning direction. A product manager role. Core perspective uses “maintainer,” not a complete alignment but similar.
    • Where is the source of truth for a block, component API, bigger featured like global styles. Where is the current state of this and how do you share it out.
      • But, would require somebody owning that role (doesn’t have to be a dev, could be a non-code role)
    • Product development lifecycle has phases. Could have deprecation be a planned documented phase.
  • We said earlier that it’s not reasonable to expect people to not use something that’s experimental. But we could do better about having defined guidelines around what something is. So for example if a new block property is added, what does that mean to officially support a block property.
    • Even if it’s partially there and unstable, if somebody knows the target idea of a feature, they can use it with greater confidence.
  • In Trac, the editor component is overly broad. How do features flow from Gutenberg to Core? Could we do things in a way that better highlights who the owners and leaders are?
  • Thinking about solutions,
    • With experimental APIs, could we add an official timeline? If something is experimental for a set amount of time, force it to go stable or go away.
    • Also, maybe should have more stages — unstable, experimental, then stable. To give a better sense of confidence where something is at.
    • Somebody mentioned that people upgrade core, and then your plugins are not compatible. Could we prevent core updates if your plugins don’t declare compatibility?
      • Widespread grimacing. Would remove upward pressure to upgrade.
  • This may be repeat. Looking at markup and CSS, there are no theme APIs. All CSS and all HTML is an API surface. Any change we make there is a breaking change.
    • Don’t have a suggestion of how to address it, but core now has a problem that previously only themes had to surface and deal with. The difference is that core is a much bigger surface area, “every site using a block theme” is impacted by core markup changes.
  • There are different degrees of BC break. An editor breakage is less bad than a frontend content break (or WSOD). A JS change may only cause an error, or one feature to fail, rather than something more widespread.
  • Considerations about data integrity, because of coupling of data and presentation. There’s an interesting paradox, it was framed as data integrity today, and rightly so, but the early decisions about how we do blocks also arose from concerns around integrity.
    • Block editor came from maybe a more pessimistic take, where Gutenberg did not change the post model but instead built blocks on top of it. Had a lot of thoughts about what happens if block editor gets deactivated, or information needs to be retrieved from the DB without the runtime.
    • Your blob of HTML in the DB might not be the same, but it still was intended to mean something to the editor. But this runs into user expectation that “things should look the same.”
    • Maybe we’re going up the pyramid of users’ needs. comfortable with idea that site doesn’t LOSE content, and are able to be more concerned with aesthetic changes or breakage.
  • Regarding idea of using healthcheck to surface issues, Nacin’s old plugin to log JS warnings was brought up. Could we do client-side inspection of things, stylesheets, can analyze code of scripts, flag usage of things. Logging in console is meaningless but if we can send it back to the site, and tie it into healthcheck, that could help quantify issues.
    • Catching deprecations is easy. But there is grey area around more sophisticated introspection with private APIs. May be more involved to flag usage of function calls, if you want to catch “calls that are taking place inside a context in which they shouldn’t.”
  • Like idea of being stricter around timeline and protocol for stabilizing or rejecting APIs — but do think that there is a human or emotional problem of commitment implicitly among people.
    • The thing we discussed yesterday around a sense of safety net in Gutenberg versus Core, in some ways this may be a form of that.
    • People are comfortable having an experimental API, they do things with it, they work. It’s easy to continue using that and you don’t know what would happen if you change something. No accountability to take the uncomfortable step of stabilizing, and “whatever happens [being] committed to fixing it.”
  • Difference between unstable and experimental already exists. Debate in group about which one we would expect to be less stable. “Unstable” in Gutenberg meant “Internal.”
  • Looking at layers, there are two different models.
    • TC39 has a proposal system, at different levels you’re looking for different types of input and providing different guarantees.
    • Node’s model has levels 0 (extremely experimental), 1 (likely to change), 2 (think this is stable), 3 (proposed final), 4 (this won’t change / break), 5 (deprecated)
  • Could look at integrating log deprecated notices with site health in contributor day.
  • One phrase that was said many years ago in WP, “WordPress takes on technical debt so that its users dont’ have to.”
    • We as contributors are OK with the idea that our lives might be harder so that the users’ are easier.
    • Are we doing experimental, etc, for the sake of us or the sake of our users? Should that paradigm change to prioritize users?
  • Thinking of areas for experimentation, maybe theme.json and block.json should only permit stable things. Can more easily version those, block.json v2 works differently than v3. We try not to update version every release, but maybe we look at packaging breaking changes together with a version bump.
    • That does provide an easier way to communicate where things have broken or changed. Easier to surface information.
  • On idea of core vs gutenberg-the-plugin, Gutenberg can be the wild west with exposing experimental APIs. Gutenberg plugin is beta software. But how do we publicize and notify users and developers?
    • Users won’t read make/core. They MIGHT read .org/news… is it work considering, the marketing dept might not love it, but are there other channels.
    • How do we do DevRel with premium plugin authors? Can’t buy every extension for every premium plugin. Does DevRel team have access? (Nope, only personal licenses).
      • Could DevRel get greater access to be able to search for API usages beyond the plugin repo.
  • Could we look at how https://sentry.io/welcome/ works and monkeypatch some small percentage of __experimental function calls
  • Premium plugin maintainers historically have seen deprecated notices and decided “i’ll deal with that when it breaks.”
    • Maybe this already exists, but it would be nice if deprecation notices had additional context and gave — particularly if a premium plugin that needs to support X versions back — when it was introduced and what timeline to update would be.
    • Took lots of manual effort to go to “which gutenberg version was this introduced” to “what version of WP did that go into” etc. Too much work.
  • For somebody who only reads make/core weekly roundup posts, easy to glaze over and see surface-level changes. Would be more approachable if there was a higher-level thematic rollup.
  • An aspect to WP releases these days, is “here’s 15 new things,” rather than a few clear marquee features. “tl;dr”, you move on.
  • On disseminating information, which is hard, make/core is impossible to keep up with:
    • Dev blog might have been a good avenue for it, but it’s currently more teaching-oriented. How do we do this in a way that doesn’t cause FUD.
    • Tavern post went up with coding standards checks calling out Juliette’s call for help, and first comment is “I’m not a developer, I’m just a user, it’s been working, this seems scary, will my site stop being secure.”
  • Regarding site health, not a huge fan of a grading score, but we did something similar with removing jQuery Migrate. Did a plugin which would log deprecation notices and let user know which plugin is causing issues, to help focus pressure from users on plugin authors and not just have it be “wordpress being difficult”.
  • Like the ideas of using TC39 or Node level strategies. We don’t have to mirror that precisely but it gives a better picture of where a feature is.
    • Would enable to get rid of experimental prefixes and instead teach when to use what
    • What do we do about existing APIs? If they’ve been in for a few releases, make them stable. Need to be pragmatic.
  • Core’s getting into this area with experimental things as well, with webfonts API which is locked from extension through the use of anonymous functions.
    • Was put in to get things moving to enable Gutenberg to experiment.
  • A good BC strategy requires us to think about future compatibility strategy, especially around how we handle content in the DB.
    • Responsive image sizes, none of that gets stored in DB. That being part of the strategy for future compat could help Gutenberg as well.
  • WP developer blog is very teaching oriented at the moment but it is a .org resource outside of make, do want to do “what’s new for developers”. Content doesn’t exist yet but it should be considered an avenue.
  • Could we make an opt-in “submit your code” mechanism for paid plugins that we can scan for issues?
  • We’ve covered a lot of cool stuff. Don’t really have consensus about expectations around the product that we want to keep in motion, because it’s a big ambitious thing. Unlike existing wordpress stack which has been there for a while and is mostly stable, there are big things that gutenberg wants to do which won’t be well established for years.
    • Users do get ticked off with g moving their cheese. Do we just acknowledge that and soldier forward. Does that bear weight on the way we do Product. Inclination is that we need to keep pushing. Don’t know any other way to go about it.
    • Open to suggestions tho.
  • Would there be interest in a breakout session about communicating breaking changes to developers?
    • Yes.

Themes

  • Have some grouping of impacted users
  • If we add more APIs, be more familiar with hurdles implementors need to work through.

#gutenberg, #summit, #summit-2023