Revisions  [[3. Resources/Readwise/Full Document Contents/Articles/Revisions|Full Document Contents]] ## Document Notes --- 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]] - [[#🧩 Block-Aware Revisions]] - [[#🖼️ Visual Diffing & Comparison]] - [[#🔁 Per-Block Restore & Multi-Entity History]] - [[#🔗 Dev Workflows, VCS, and CLI]] - [[#🎛️ Global Styles & Patterns]] - [[#🧱 Storage, Performance, and Architecture]] - [[#🧶 Grouping, Naming, and Changesets]] - [[#🧪 Scope Summary]] - [[#📌 Extended Revisions & Scheduling]] - [[#📚 References]] ### 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 > [!note]+ Document Notes > 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 > <!-- deep-read:sections start --> ## 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-source transparency, contributor experience, and interoperability with VCS/CLI; identify opportunities to design learning pathways, governance policies, and inclusive collaboration rituals aligned with WordPress community values.” ## 🧪 Hypotheses: - Visual, block-aware diffs reduce review time and error rates compared to HTML diffs. - Per-block restore increases contributor confidence and decreases full-post rollbacks. - Grouped/named revisions improve cross-functional collaboration in large teams. - Changeset-based multi-entity history reduces merge conflicts in collaborative editing. - File-based export to VCS increases adoption in enterprise and agency workflows. ### 📊 Methodology: - Mixed-methods UX study: time-on-task for reviewing/merging changes with visual vs HTML diffs; measure error rates. - A/B in production: enable per-block restore for a cohort; track rollback scope and frequency. - Telemetry: diff view usage, property-level style changes viewed, restore granularity chosen. - Survey/interviews: developers using git/wp-cli flows; barriers, satisfaction, and adoption metrics. - Performance profiling: storage reads/writes for revisions at scale; stress test posts tables. - Multilingual simulation: test changeset branching across locales and entities. ### ❓ Questions: - How should nested block histories be visualized for clarity without overwhelming users? - What minimum metadata is needed to make a diff explainable (who, what property, where in hierarchy, why)? - How do we safely map editor changes to stable file representations for clean VCS diffs? - What is the governance model for naming/grouping revisions—permissions, workflows, audit? - How will multilingual content interact with entity-scoped histories and cross-entity references? ### 🔮 Future Research: - Standard schema for block-level diff metadata and visual rendering. - Conflict resolution UX patterns for real-time + offline scenarios. - Cross-entity branching strategies and safe merge semantics. - Accessibility-first diffing (color-blind safe palettes, screen-reader narratives). - Educational patterns for onboarding contributors into revisions + VCS pipelines. ### 💡 Implications: - Advances collaboration UX, narrowing the gap between CMS authors and engineering teams. - Improves auditability and compliance for enterprises adopting WordPress. - Creates a foundation for multilingual and multi-entity content governance. - Encourages ecosystem tooling (plugins/CI) around revisions-as-first-class. ### 🧠 Learning Styles Assessment: - Readability: Likely upper-intermediate technical (approx. Grade 10–12) due to domain terms. 1) Visual - Present: Conceptual references to visual diffs and mockups. - Improve: Include diagrams of per-block histories, nested structures, and side-by-side/overlay examples. 2) Aural - Present: None. - Improve: Provide an audio summary or short podcast segment with design leads. 3) Verbal - Present: Clear descriptions; references to use cases and entities. - Improve: Add analogies (e.g., “track changes” in docs) and more examples. 4) Physical - Present: None. - Improve: Interactive prototypes and click-through demos. 5) Logical - Present: Stepwise scope list and architectural considerations. - Improve: Decision trees for restore flows; matrices for entity relationships. 6) Social - Present: Implicit collaboration context. - Improve: Link to discussion threads, calls for testing, and working groups. 7) Solitary - Present: Structured text. - Improve: Reflection prompts and checklists for implementers. 8) Naturalistic - Present: None. - Improve: Use nature analogies for branching/merging to aid conceptual grasp. ### 📊 Accessibility Assessment: - Screen Reader: Likely standard blog HTML; limited alt-text detail for mockups. - Improve: Provide full alt-text and ARIA descriptions for diff visuals. - Keyboard Navigation: Core blog is generally navigable, but diff UIs must ensure focus states and tab order. - Improve: Define keyboard shortcuts for diff navigation and restore actions. - Contrast & Readability: Ensure diff highlight colors meet WCAG AA; support dark mode. - Text Resizing: Ensure responsive typography and non-overlapping overlays when zoomed. ### 🌍 DEIB (Diversity, Equity, Inclusion, and Belonging) Assessment: - Cultural Relevance: Neutral technical focus; minimal global perspectives. - Improve: Include multilingual, RTL, and low-bandwidth contexts. - Inclusive Language: Mostly neutral; some domain jargon. - Improve: Glossary for terms like “customize_changeset,” “multi-entity.” - Neurodiversity Support: Dense sections. - Improve: More headings, bullet points, and summaries per section. - Representation: No examples or case studies. - Improve: Highlight diverse contributor stories and use cases. - Psychological Safety: Neutral tone. - Improve: Invite feedback, code of conduct references, and safe channels for critique. ### ✅ Logical validity: - Strengths - Logical flow: Problem (HTML diffs) → Solution (visual, block-aware) → Integration (VCS, CLI) → Architecture (multi-entity, performance). - Inductive reasoning: Visual diffs likely improve comprehension in block contexts; aligns with known usability principles. - Causal reasoning: Per-block restore should reduce over-reversion and improve accuracy. - Weaknesses - Evidence gaps: No empirical data cited. - Potential false dilemma avoided: Acknowledges VCS is complementary, not replaced. - Suggestions - Add user research data, benchmarks, and case studies. - Provide counterarguments (complexity costs, training burden) and mitigations. Tone: Professional, forward-looking, solution-oriented. DARVO analysis: - No signs of Deny, Attack, or Reverse Victim/Offender. The document is a technical proposal without adversarial framing or personal attribution. ### 🔍 SEO Evaluation: 1) Keywords: Present (WordPress, revisions, blocks, global styles, patterns, customize_changeset, version control, wp-cli). Integrate naturally in intro and headers. 2) Meta Description: Add a concise summary with “WordPress revisions,” “block editor,” “visual diffing.” 3) Title Tag: “Revisions” is generic; optimize to “WordPress Revisions for the Block Editor: Visual Diffing, Per-Block Restore.” 4) Headers: Use H2/H3s with key terms (Block Revisions, Visual Diff, Global Styles). 5) Content Length: Adequate for announcement; expand with examples to reach 1,200–1,800 words. 6) Links: Add internal links to Core docs, Gutenberg issues; external to WP-CLI, Git docs. 7) URL: Good, concise and descriptive. 8) Images: Ensure alt-text with keywords; optimize sizes. 9) Mobile: Ensure images and code samples responsive; test page speed. 10) Engagement: Add calls for testing, links to prototype, comments. 11) Schema: Use Article schema; consider HowTo/FAQ if adding usage instructions. 12) Social: Ensure Open Graph/Twitter Card with a compelling image of visual diffs. ## 🎯 Conclusion: WordPress is charting a modern revisions system that’s native to blocks, visually intelligible, and deeply collaborative. By enabling per-block history and restoration, side-by-side and overlay comparisons, multi-entity orchestration via changesets, and VCS/CLI touchpoints, this proposal bridges authoring, design, and development workflows. It prepares Core for multilingual complexity, improves auditability and performance considerations, and opens space for plugin innovation. For educators, advocates, and OSPO leaders, it’s an opportunity to build inclusive pathways that teach, govern, and scale open collaboration. <!-- deep-read:sections end --> ## Highlights - 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/). ([View Highlight](https://read.readwise.io/read/01h5jrkzht82ddccmyzapcep6f))