Block Deprecation Secrets Only WordPress Experts Know 🔗 **Source:** [Block Deprecation Secrets Only WordPress Experts Know](https://www.youtube.com/watch?v=nE3tXm4qkFs) > [!note]+ Document Notes > tags: > - #WordPress > - #Gutenberg > - #BlockDeprecation > Author: Presenter not specified in transcript (channel/author name not stated) > Source: YouTube (video tutorial) > Reference: https://www.youtube.com/watch?v=nE3tXm4qkFs > date created: 2025-08-20 11:56 > > # 🧩 Title: Block Deprecation Secrets Only WordPress Experts Know — A Practical Walkthrough > <!-- deep-read:sections start --> ## 🧭 Table of Contents: - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [♿ Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [🧮 Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🔍 SEO Evaluation](#-seo-evaluation) - [🎯 Conclusion](#-conclusion) ### 📎 References: Include a list of sources consulted and cited in the article. ## 📝 Summary: - 🔹 **What it is:** A hands-on demo that shows how to prevent and fix block validation errors by using **block deprecations** in WordPress. - 🔹 **Scenario:** You inherit a static **recipe** block, then change its markup, add a `title` attribute, rename it to `name`, and later convert hardcoded markup to **InnerBlocks**. - 🔹 **Core lesson:** Keep a **`deprecated` array** for prior versions. Include the **old `save()`** and **old `attributes`**, and optionally a **`migrate()`** to transform data. - 🔹 **Why it matters:** You avoid the “This block contains unexpected or invalid content” error across many posts and keep editors happy. ## 📖 Main Content: - 🔹 **Setup & aim** ([0:00](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=0)–[0:40](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=40)) - 🔸 Presenter introduces **block deprecations** and prepares a sandbox plugin. - 🔸 Goal: Show markup changes, attribute changes, and InnerBlocks migration without breaking existing content. - 🔹 **Baseline static block** ([1:10](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=70)–[1:47](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=107)) - 🔸 “Greatest chocolate chip cookie recipe” renders as simple static markup. - 🔸 No attributes yet; everything is hardcoded. - 🔹 **First change: markup toggle** ([1:50](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=110)–[3:04](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=184)) - 🔸 Replace recipe content in **`edit.js`** and **`save.js`** to add show/hide behavior. - 🔸 Refresh causes a **validation error** because new **`save()`** output ≠ saved post HTML. - 🔹 **Add a deprecation for markup** ([4:23](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=263)–[6:46](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=406)) - 🔸 Create **`deprecations.js`** with an array of versions. - 🔸 Add an entry with the **old `save()`** and **old `attributes`** (none yet). - 🔸 After rebuild and refresh, the error clears; the editor can reconcile versions. - 🔹 **Add `title` attribute with RichText** ([7:57](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=477)–[10:15](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=615)) - 🔸 Introduce `attributes.title` in **`block.json`**. - 🔸 Swap `<h2>` with **`RichText`** in `edit.js` and **`RichText.Content`** in `save.js`. - 🔸 Save a custom title; everything still validates. - 🔹 **Rename attribute: `title` → `name`** ([10:55](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=655)–[14:33](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=873)) - 🔸 Update **`block.json`**, `edit.js`, `save.js`. - 🔸 Refresh yields **another validation error** because stored posts still have `title`. - 🔸 Fix by adding a **second deprecation entry** that lists old `attributes` and uses **`migrate({ title }) => ({ name: title })`**. - 🔹 **Convert hardcoded sections to InnerBlocks** ([15:45](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=945)–[20:20](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=1220)) - 🔸 Build a **template** with two `core/details` blocks each containing a `core/list`. - 🔸 In `edit.js`, render `<InnerBlocks template=[…] allowedBlocks=['core/details','core/list'] />`. - 🔸 In `save.js`, render `<InnerBlocks.Content />`. - 🔸 If a validation error occurs, add a **third deprecation** that replays old hardcoded markup and uses **`migrate(_, innerBlocks)`** to **create** list items and **return** `{ name, innerBlocks }`. - 🔹 **Takeaways** ([20:33](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=1233)–[21:08](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=1268)) - 🔸 Deprecations are normal for **static** blocks; dynamic blocks don’t need them. - 🔸 Gather the old `save()` and `attributes` **before** refactors. ### 🗒️ Notes - 🔹 **Block validation error — cause & fix** - 🔸 Cause: new **`save()`** output doesn’t **match** the old post HTML ([3:04](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=184)–[4:05](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=245)). - 🔸 Fix: add **deprecation entries** with the **previous** `attributes` and **previous** `save()`. - 🔸 Optional: write **`migrate(attributes, innerBlocks)`** to transform data across versions. - 🔹 **Workflow pattern** - 🔸 ✅ **Before** changing markup: copy the old `save()` into `deprecations`. - 🔸 ✅ For attribute renames: keep old **shape** in `attributes`, then map in `migrate`. - 🔸 ✅ For markup → InnerBlocks: reconstruct blocks in `migrate` and return `innerBlocks`. - 🔹 **RichText swap** ([7:57](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=477)–[10:15](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=615)) - 🔸 `edit.js`: `RichText tagName="h2" value={attributes.title} onChange={(v)=>setAttributes({ title:v })}`. - 🔸 `save.js`: `<RichText.Content tagName="h2" className="…" value={attributes.title} />`. - 🔹 **Attribute rename** ([10:55](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=655)–[14:33](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=873)) - 🔸 Old: `title:string`, New: `name:string`. - 🔸 Deprecation: `attributes:{ title:{type:'string',default:'Classic…'} }`, `save()` uses `title`. - 🔸 `migrate({title}){ return { name:title }; }`. - 🔹 **InnerBlocks migration** ([15:45](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=945)–[19:18](https://www.youtube.com/watch?v=nE3tXm4qkFs&t=1158)) - 🔸 Build arrays of **created** `core/list-item` blocks from prior content. - 🔸 Create two parent `core/details` blocks with those items as children. - 🔸 Return `{ name, innerBlocks:[…details blocks…] }` from `migrate`. - 🔹 **Tone & style** - 🔸 Conversational, pragmatic, slightly cheeky (“shut up, it’s my template”). - 🔸 Teaches by doing; shows failures, then fixes. - 🔸 Bias: favors **static** blocks to demo deprecations; notes dynamic as an escape hatch. ## 📚 References: - 🔹 Video transcript source: https://www.youtube.com/watch?v=nE3tXm4qkFs - 🔹 WordPress Docs — Block Deprecation (concept + examples): https://developer.wordpress.org/news/2023/03/block-deprecation-a-tutorial/ - 🔹 Block Editor Handbook — Deprecation API: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/ - 🔹 Block Editor Handbook — `RichText`: https://developer.wordpress.org/block-editor/reference-guides/richtext/ - 🔹 WP.org Doc — “Unexpected or invalid content” overview: https://wordpress.org/documentation/article/block-error-unexpected-or-invalid-content/ - 🔹 GitHub discussion — using `migrate` with `innerBlocks`: https://github.com/WordPress/gutenberg/discussions/37744 ## 🗣️ Paraphrase: - 🔹 **Why the first error appears** - 🔸 Original: The **`save.js`** output doesn’t match the existing post HTML, so the editor throws a validation error. - 🔸 Paraphrase: The editor compares the current **`save()`** render to the old stored HTML. If they differ, it flags the block as invalid. - 🔹 **What a deprecation actually does** - 🔸 Original: A `deprecated` entry tells the editor how the block **used to** look and how to map it forward. - 🔸 Paraphrase: You ship a time capsule of prior versions. The editor uses it to translate old content into the new shape. ## 📰 Newsletter: - 🔹 **Learn web dev:** Today’s bite is all **Gutenberg deprecations**. You’ll keep editors calm and content safe. - 🔹 **Updates:** We walk through markup refactors, attribute renames, and **InnerBlocks** migrations without nuking posts. - 🔹 **Community:** Share your best `migrate()` snippets in the #core-editor channel or forums. - 🔹 **Plugins:** If your static blocks keep changing, consider a **dynamic** version for stability. - 🔹 **Links:** Tutorial video ➜ https://www.youtube.com/watch?v=nE3tXm4qkFs • Docs ➜ https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/ ## ✅ Action Items: - 🔹 **Reusable evaluation prompt (aligned to your advocacy + OSPO path):** - 🔸 “Evaluate how this resource supports **open-source contributor onboarding** in WordPress. Map takeaways to: 1) contributor education for **block authors**, 2) **transparency** in change management (changelogs, deprecations), 3) **sustainability** via reduced editor friction, 4) materials for **Learn WordPress**, 5) OSPO-aligned governance: migration policies, versioning, and support windows. Produce TL;DR, contributor tasks, KPIs (invalid-block rate, time-to-fix), DEIB notes, and risks.” - 🔹 **Do next (program + edu):** - 🔸 Publish a **Learn WordPress** lesson: “Deprecations 101 with `migrate()` and `InnerBlocks`.” - 🔸 Add a **repo policy**: every breaking change must include **deprecation + migration** and a screenshot/GIF. - 🔸 Set a **KPI**: reduce “unexpected/invalid content” occurrences by **30%** quarter-over-quarter across sample sites. - 🔸 Create a **reference cookbook** of attribute rename patterns (`title`→`name`, etc.) with tests. ## 🧪 Hypotheses: - 🔹 H1: Shipping deprecations with each markup change cuts invalid-block errors by **≥40%** within two releases. - 🔹 H2: A shared `migrate()` snippet library raises successful migrations by **≥25%** for first-time block authors. - 🔹 H3: Publishing an a11y-safe InnerBlocks template improves editor success rates by **≥15%**. ### 📊 Methodology: - 🔹 **Design:** Pre/post analysis on pilot plugins across 10–20 client sites. - 🔹 **Data:** Site health logs, editor error telemetry, GitHub issues, support tickets. - 🔹 **Analysis:** Interrupted time series; classify failures by **markup**, **attribute**, **innerBlocks**. ### ❓ Questions: - 🔹 Which deprecation patterns cover **80%** of real-world block refactors? - 🔹 When should teams stop deprecating and ship a **new** block name instead? - 🔹 How can we auto-generate `deprecated` entries from diffs? ### 🔮 Future Research: - 🔹 Build a **CLI** that snapshots `save()` + `attributes` before refactors and scaffolds `deprecated` entries. - 🔹 Explore **dynamic** fallbacks for frequently-changing blocks to reduce deprecation churn. - 🔹 Study editor UX cues that guide users during migrations. ### 💡 Implications: - 🔹 Better deprecation hygiene cuts support costs and editor frustration. - 🔹 OSPOs can treat block migrations as **governance artifacts**, improving trust and transparency. ### 🧠 Learning Styles Assessment: - 🔹 **Readability:** Conversational technical tutorial; ~Grade **9–10**. 1. 🔹 **Visual (Spatial)** - 🔸 Present: On-screen code changes implied; minimal diagrams. - 🔸 Improve: Add flowcharts for **before/after** `save()` and `migrate()`. 2. 🔹 **Aural (Auditory)** - 🔸 Present: Spoken walkthrough. - 🔸 Improve: Provide a short audio recap and chaptered timestamps. 3. 🔹 **Verbal (Linguistic)** - 🔸 Present: Step-by-step narration with examples. - 🔸 Improve: Glossary for `deprecated`, `migrate`, `InnerBlocks`. 4. 🔹 **Physical (Kinesthetic)** - 🔸 Present: Live coding pace invites replication. - 🔸 Improve: Downloadable repo + exercises per step. 5. 🔹 **Logical (Mathematical)** - 🔸 Present: Clear cause → effect (mismatch → error → deprecate). - 🔸 Improve: Decision tree: **deprecate vs new block vs dynamic**. 6. 🔹 **Social (Interpersonal)** - 🔸 Present: Tutorial-only. - 🔸 Improve: Link to discussion threads and office hours. 7. 🔹 **Solitary (Intrapersonal)** - 🔸 Present: Transcript aids self-study. - 🔸 Improve: Self-check prompts after each refactor. 8. 🔹 **Naturalistic** - 🔸 Present: Not applicable. - 🔸 Improve: N/A. ### 📊 Accessibility Assessment: - 🔹 **Screen Reader:** Ensure semantic headings in show notes; label code blocks. - 🔹 **Keyboard:** Provide focus-visible states in example UIs; avoid tab traps in details/summary demos. - 🔹 **Contrast:** Use WCAG 2.2 AA in code overlays; avoid low-contrast comments. - 🔹 **Text Resizing:** Make code panes responsive and scrollable at 200–400% zoom. ### 🌍 DEIB Assessment: - 🔹 **Cultural Relevance:** Technical focus; broaden examples to teams of varied sizes and regions. - 🔹 **Inclusive Language:** Avoid jargon without definitions; keep tone respectful and welcoming. - 🔹 **Neurodiversity:** Chunk steps; add checklists and predictable patterns. - 🔹 **Representation:** Invite community examples from diverse contributors. - 🔹 **Psychological Safety:** Normalize mistakes; show non-punitive recovery paths. ### 🧮 Logical Validity: - 🔹 **Sound reasoning:** - 🔸 *Causal chain:* New markup/attributes → mismatch → validation error → deprecations + migration resolve it. - 🔸 *Consistency:* Same rules applied across markup, attribute rename, and InnerBlocks. - 🔸 *Counterexample covered:* Dynamic blocks don’t store HTML; they avoid these errors. - 🔹 **Potential gaps:** - 🔸 No formal data on error rates; future work should add metrics. - 🔹 **Tone of voice:** - 🔸 Practical, humorous, candid about pain points; focuses on fixes, not blame. - 🔹 **Fallacy scan:** - 🔸 No strawman or false dilemma; the tutorial compares **deprecate**, **recover**, and **dynamic** calmly. ## 🛡️ DARVO Analysis: - 🔹 **Deny:** Not present. The tutorial openly acknowledges errors and shows them on-screen. - 🔹 **Attack:** Not present. No personal attacks or blame; critique stays on code and process. - 🔹 **Reverse Victim and Offender:** Not present. The editor is not framed as the villain; the mismatch is the issue. - 🔹 **Notes:** Language remains instructive and empathetic; no DARVO tactics appear. ### 🔍 SEO Evaluation: 1. 🔹 **Keywords:** “WordPress blocks,” “Gutenberg deprecations,” “block validation error,” “InnerBlocks migration.” 2. 🔹 **Meta description:** Add a 150–160 char summary including “Gutenberg deprecations” and “migrate.” 3. 🔹 **Title tag:** Keep under 60 chars; include “WordPress Blocks” + “Deprecations”. 4. 🔹 **Headers:** Use H2/H3 for “Markup change,” “Attribute rename,” “InnerBlocks migration.” 5. 🔹 **Length:** Aim for 1,200–1,800 words in show notes with clear sections. 6. 🔹 **Links:** Internal links to related block tutorials; external links to WP docs. 7. 🔹 **URL:** Use concise slug, e.g., `/gutenberg-block-deprecations-migrate`. 8. 🔹 **Images:** Include step diagrams; add descriptive **alt** text and compressed assets. 9. 🔹 **Mobile:** Optimize video embed; lazy-load iframes. 10. 🔹 **Engagement:** Add “Try it” checklists and code snippets. 11. 🔹 **Schema:** Use `VideoObject` + `Article`; add timestamps via `Clip` markup if possible. 12. 🔹 **Social:** Provide Open Graph image with code overlay; set Twitter Card to `summary_large_image`. ## 🎯 Conclusion: - 🔹 **Bottom line:** Deprecations prevent chaos when blocks evolve. - 🔹 **Playbook:** Save the **old** `save()` and `attributes`, write **`migrate()`** when shapes change, and consider **InnerBlocks** for flexibility. - 🔹 **Outcome:** Fewer invalid blocks, smoother editor experience, and a maintainable upgrade path for teams and clients. <!-- deep-read:sections end -->