Revisions ![rw-book-cover](https://make.wordpress.org/core/files/2023/07/image.png) ## Metadata - Author: [[Make WordPress Core]] - Full Title: Revisions - Category: #articles - Document Note: --- tags: - #wordpress - #gutenberg - #revisions - #collaboration - #blockeditor - #versioncontrol - #globalstyles - #patterns - #customizechangeset - #multilingual Author: Make WordPress Core Source: Make/Core Blog Reference: https://make.wordpress.org/core/2023/07/05/revisions/ date created: {{date:YYYY-MM-DD}} {{time:HH:mm}} --- # Title: Reimagining WordPress Revisions for Block-Based Collaboration ## Table of Contents: - [🧭 Overview](#-overview) - [🧩 Block-Aware Revisions](#-block-aware-revisions) - [🖼️ Visual Diffing & Comparison](#️-visual-diffing--comparison) - [🔁 Per-Block Restore & Multi-Entity History](#-per-block-restore--multi-entity-history) - [🔗 Dev Workflows, VCS, and CLI](#-dev-workflows-vcs-and-cli) - [🎛️ Global Styles & Patterns](#️-global-styles--patterns) - [🧱 Storage, Performance, and Architecture](#-storage-performance-and-architecture) - [🧶 Grouping, Naming, and Changesets](#-grouping-naming-and-changesets) - [🧪 Scope Summary](#-scope-summary) - [📌 Extended Revisions & Scheduling](#-extended-revisions--scheduling) - [📚 References](#-references-1) ### References: - Make/Core: Revisions proposal and scope - WordPress Core docs on revisions and customize_changeset - WP-CLI and VCS workflows (git, svn) ## 📝 Summary: The article outlines a Phase 3 vision for transforming WordPress revisions into a block-aware, visually rich, and collaboration-ready system. It proposes moving beyond HTML markup diffs toward visual comparisons, enabling per-block history and restoration, integrating with global styles and synced patterns, and aligning with real-time collaboration, offline conflict resolution, and developer workflows. It also raises architectural considerations for multi-entity history, storage/performance, multilingual in Phase 4, and orchestrated revision grouping via customize_changeset. Key ideas include: - Visual comparison modes (side-by-side and overlays) for block changes. - Per-block browsing and restoring of changes, including nested contexts. - Multi-entity revision orchestration and branching via changesets. - Interoperability with git/svn and wp-cli for file-based workflows. - Enhanced clarity on what changed (e.g., typography, palettes) within global styles. ## 📖 Main Content: The article argues that traditional revision diffs fall short for the block editor era. Instead of raw HTML deltas, users need visual, contextual diffs that reflect how blocks look and behave. The vision encompasses: - A unified revision experience spanning posts, blocks, global styles, and patterns. - The ability to zoom into any block—even inside nested structures—and view its entire change history. - Restoration granularity, allowing selective reverts per block without rolling back an entire post. - Improved UX for comparing style changes, identifying properties changed, and staging grouped changes with names. - Bridges between Core revisions and developer version control, ensuring site editor changes can be persisted to the filesystem for git/svn workflows. - A broader architectural plan that considers conflict resolution in collaborative editing, offline reconciliation, and multilingual content management. ### 🗒️ Notes - Collaboration & clarity - Revisions must be clear, usable, performant. - Move beyond classic HTML diffs to block-aware visuals. [Intro] - Block-level history - Select a block and see its change history; nested contexts respected. [Scope] - Restore at document or per-block level to avoid full post rollback. [Scope] - Visual comparison - Side-by-side and overlay comparisons for content, global styles, and patterns. [Intro, Scope end] - Highlight property-level changes (e.g., palettes, typography). [Scope end] - Multi-entity orchestration - Conflicts in real-time/offline editing intersect with revision restore flows. [Middle] - Consider branching for multi-entity history; link related entities via changesets. [Scope] - Developer workflows - Revisions aren’t a replacement for VCS; ensure bidirectional points of contact. [Middle] - Enable saving site editor changes to files; support git/svn and wp-cli. [Middle] - Architectural considerations - Evaluate storage/performance of revision systems (e.g., posts tables). [Scope] - Plan for multilingual needs in Phase 4. [Middle] - Grouping & naming - Investigate grouping/naming revisions for staging and clarity. [Scope end] - Connect Site Editor “save” to customize_changeset. [Middle, Scope end] - Scheduling - Review extended revisions plugin for scheduling updates to published posts. [Scope end] Direct anchors for key sections: - Overview (Introduction): https://make.wordpress.org/core/2023/07/05/revisions/ - Conflict resolution & VCS alignment: https://make.wordpress.org/core/2023/07/05/revisions/ - Scope list: https://make.wordpress.org/core/2023/07/05/revisions/ ## 📖 References: - Make WordPress Core: Revisions proposal - WP-CLI: Command line integration for content and config management - customize_changeset API in WordPress Core ## 🗣️ Paraphrase: 1) Original idea: “Traditional post revisions need to become block-aware and provide better visual comparisons than HTML diffs, with easy mechanisms to spot changes across content types.” Paraphrase: The revisions interface should understand blocks, showing visual, not just markup-based, differences and helping users quickly identify changes across all kinds of content. 2) Original idea: “Internal WP revisions are not a substitute for version control, so there must be touchpoints that let developers move changes between WordPress and the filesystem for git/svn, potentially via wp-cli.” Paraphrase: Because Core revisions can’t replace Git or SVN, WordPress needs integration points that allow teams to export site changes to files and manage them through standard developer tooling, including command-line workflows. ## 📰 Newsletter: WordPress is rethinking revisions for the block era—and it’s a big deal. Imagine diffing actual block visuals (not just HTML), zooming into a single block’s history—even nested ones—and restoring only what you need. Global Styles? Compare side-by-side, spot exactly what changed (palettes, typography), and even stage grouped changes. Devs, rejoice: the plan includes touchpoints for file-based workflows so site editor changes can live in git/svn with wp-cli in the loop. This also lays groundwork for conflict resolution in collaborative editing and multilingual in Phase 4. If you build teams, themes, or tooling, keep an eye on customize_changeset to orchestrate multi-entity history. Read more on Make/Core: WordPress Revisions proposal (block-aware, visual diffing, per-block restore). Link: https://make.wordpress.org/core/2023/07/05/revisions/ ## ✅ Action Items: Prompt for alignment with your Developer Advocate and OSPO ambitions: - In one paragraph: Explain how block-aware, visual revisions support contributor onboarding by making change history easier to understand and teach (PHP/JS/HTML/CSS/Git). - Map how per-block restore and multi-entity changesets enable sustainable collaboration, reduce rework, and foster transparency in open-source processes. - Detail how VCS touchpoints (git/svn + wp-cli) connect education with real-world DevOps, enhancing contributor confidence and lowering the barrier to entry. - Outline how grouping/naming revisions improve inclusive review practices, enabling peer review, pair programming, and structured mentoring across time zones. - Connect storage/performance and multilingual considerations to OSPO governance: policy for data portability, auditability, and internationalization readiness. - Propose a contributor education module: “From Site Editor to Git”—hands-on exercises that export changes to files, review with PRs, and deploy back. - Define metrics to evaluate engagement: revert accuracy, review time per patch, onboarding time-to-first-PR, and contributor retention. - Close with how this article’s direction advances your goal to lead an OSPO by aligning product UX, contributor education, and sustainable funding narratives. Use this as a reusable prompt when reviewing future articles: “Analyze how the proposal enhances open-sou - Document Tags: [[gutenberg]] [[phase 3]] [[wordpress]] - Summary: The document discusses the need to improve the revisions interface and architecture in order to enhance collaboration workflows. The traditional post revisions interface should evolve to incorporate blocks and offer better visual comparison capabilities. The interface should also allow users to browse and restore individual block changes instead of requiring full post restores. Furthermore, the document highlights the need to address conflict resolution, version control system integration, and customization of revisions. The scope of the project includes designing a more comprehensive revisions interface, integrating with blocks, improving visual comparison tools, and exploring ways to group and name revisions. - URL: https://make.wordpress.org/core/2023/07/05/revisions/ This is part of the **Phase 3: Collaboration** roadmap. The main projects are [Real-Time Collaboration](https://make.wordpress.org/core/2023/07/03/real-time-collaboration/), [Workflows](https://make.wordpress.org/core/2023/07/04/workflows/), [Revisions](https://make.wordpress.org/core/2023/07/05/revisions/), [Media Library](https://make.wordpress.org/core/2023/07/07/media-library/), [Block Library](https://make.wordpress.org/core/2023/07/10/block-library/), and [Admin Design](https://make.wordpress.org/core/2023/07/12/admin-design/). #### Introduction Collaboration workflows require revisions and edit history to be clear, usable, and performant. The design of the traditional post revisions interface needs to evolve to become fully aware of blocks. It should offer better visual comparison capabilities beyond the classic HTML code diffing, which is getting less and less adequate for illustrating block modifications. It should provide easy mechanisms for spotting changes regardless of the content type being shown. [![Mockup showing a paragraph block with three words highlighted in green as "additions".](https://make.wordpress.org/core/files/2023/07/image.png)](https://make.wordpress.org/core/files/2023/07/image.png) As part of improving the overall experience, we should also go beyond document level history and explore how the interface could let users browse through single block changes and offer the ability to restore them individually rather than requiring full post restores. For global styles, we should evolve the revisions panel to allow comparing two revisions side by side. For synced patterns, we could allow browsing edit history with side by side and overlay comparison tools. There’s also a semantic overlap between conflict resolution in real-time collaboration, offline reconciliation, and restoring or managing edit history. At the same time, internal revisions in WordPress are not a replacement for version control systems, so there has to be points of contact to ensure developers can lift from or deploy changesets down to the filesystem as needed. Plugins should also be able to extend the capabilities and develop more advanced integrations on top of what Core provides. For example, consider the case of using all the site editor tools but ensuring user modifications are saved back into files so they can be managed by `git` or `svn` workflows, including `wp-cli` integrations. Exploring some of these problems should also help outline what architectural considerations multi-lingual would present in *Phase 4* when managing content over all possible site objects. Finally, we should investigate if we can adapt `customize_changeset` to orchestrate revision grouping across all new entities and requirements — such as grouping multiple revisions together, reference and orchestrate changes to entities, etc. #### Scope This is a summary of the broad tasks we need to look into: * Design a revisions interface that can better highlight visual differences beyond markup diffing. Align presentation of *added* & *removed* content with how edit suggestions might be presented in the other collaborative workflows. * Integrate with blocks. Allow selecting a block (like an image) and see all changes that have occurred to it. It should work out of the box with nested contexts, so if you select a parent it tracks and shows changes across all its children as well. Users should be able to focus at any level within a document. * Make it easy to restore changes on a document or per block basis. For example, reverting some design changes to an embedded pattern but keeping the rest of the post as is, even if the pattern is not synchronized separately. The flows for restoring should be connected with the flows for publishing, so a revision can be made the currently published view. * Explore ways in which branching could work for multi-entity history. For example, site title changes won’t be naturally covered in the edit history of a template that contains a site title block, but it could be referenced through a customizer changeset that connects template revision and discrete entity values. The multi-entity saving flow should evolve to take this into account. * Evaluate any possible shortcomings in storage and performance of the various revision systems if they are to be used broadly (for example, everything going through posts tables). * Improve the visual comparison tools so a user can check their content side by side or using overlays to spot differences. This can be rehearsed on the global styles revisions history and focused pattern views. * Develop more immediate clarity over what properties were changed on certain revisions. For example, on style revisions list if there were changes to color palettes, to typography, etc, to improve the browsing experience. * Explore viability of naming or grouping revisions, particularly for staging changes in the future. Connect “save” area in site editor flows with `customize_changeset` or equivalent. Keep track and list entity modifications. * Review the *[revisions extended](https://github.com/wordpress/revisions-extended)* plugin for scheduling updates to already published posts. #### Get Involved! If you are interested in helping improve the revision interfaces and architecture, please join in., Revisions, Make WordPress Core, 01h5jn43aherc6gfd25gyxqqaw.