/ Project Handbook

Plugin/Block Release Checklist

This handbook page outlines the essential requirements and guidelines for preparing WordPress plugins and blocks for release to our public GitHub repo and website, covering everything from pre-release documentation to quality standards.

  1. Pre-Release Requirements
  2. Block Style Guide
  3. Publishing Workflow
  4. Feedback & Maintenance Process
  5. Quality Standards

Pre-Release Requirements

Documentation & Metadata

  • README file is complete with no placeholder text
    • Includes expected default behavior
    • Documents all available settings
    • Provides clear usage instructions
  • Plugin author name is the Special Projects team account (unless it’s submitted to DotOrg, in which case the author is the team plus all contributors/contractors)
  • Version number is properly assigned (minimum 0.1.0 for public release)
  • Block/plugin name follows naming conventions (see Style Guide below)

Design Assets

  • Featured image/icon created by design team
  • Screenshots showing the block in use
  • Video demonstration (if applicable)
  • Short excerpt describing the block’s purpose

Technical Standards

  • Style guide adherence confirmed
  • Custom insert icon is relevant to the block’s function
  • Relevant block category specified (Design, Theme, etc.)
  • Block settings align with standard block tools and behavior
  • Accessibility compliance with WCAG standards verified (where relevant)
  • Right-to-left language support (where relevant)

Testing Validation

Complete functional testing checklist:

  • Installation & Basic Functionality
    • Follow README instructions — does it work as expected?
    • Access via block search
    • Search for block using “/[block name]” command in the editor
  • Platform Testing
    • Editor functionality: desktop browser (consider variety of browser types), mobile browser
    • Published page/post display: desktop browser (consider variety of browser types), mobile browser
  • Block Discovery
    • Block appears in relevant category for its use case
    • Block has custom icon and preview visible in search
  • Additional Testing (as relevant to specific functionality)

Block Style Guide

Naming Conventions

  • Use title case
  • Omit the word “block” from the name
  • Ensure name is discoverable and clearly indicates purpose

Block Search & Discovery

  • Include preview image in block search
  • Assign to appropriate category
  • Provide custom, relevant icon

User Experience

  • Expected behavior clearly documented in README
  • Known limitations or “not yet in scope” scenarios identified
  • Default behavior is intuitive (document any non-obvious behaviors)
  • Once installed, the description on the plugin page is accurate and descriptive.

Publishing Workflow

Project Milestones (Linear Template)

  1. Design Review — UI review completed
  2. Functional Testing — Workflow testing 
  3. Call for Testing — Publish P2 for community testing
  4. Design Assets — All visual materials prepared
  5. Screenshots & Video — Documentation media gathered
  6. Website Publication — Published to specialprojects.automattic.com/tools
  7. Example Page — Added to http://block-library-production.mystagingwebsite.com/
  8. Blog Post — Announcement published on public website

Website Publication Checklist

  • Featured image (from design team)
  • Screenshots of block in use
  • Video (if applicable)
  • Short excerpt of the block’s purpose
  • Content from plugin README
  • Version number
  • GitHub link (from https://github.com/a8cteam51/special-projects-blocks-monorepo/tags)
  • Download link (plugin zip from GitHub release page assets)
  • Link to example block on block-library-production.mystagingwebsite.com

Inclusion in the Monorepo (TAM tasks)

  • Clearly outline block specifications if working on a project
  • Review block settings for compliance with standard block tools and settings behavior
  • Verify custom insert icon is relevant

Feedback & Maintenance Process

Submitting Feedback

Internal:

  1. Create new issue in Linear for the Cool Tools Team ███████████████ (Issue syncs to GitHub)
  2. Lands in Triage queue

External:

  1. Create new issue in GitHub (Issue syncs to Linear)
  2. Lands in Triage queue

Triage Process

  • Task Force: Can triage and open dev request if urgent
  • TAMs: Can triage to assign to contractor if appropriate

Quality Standards

Minimum Viable Product (MVP)

  • Blocks must be version 0.1.0 or higher before public release
  • Core functionality is stable and tested
  • Documentation is complete and accurate

Advanced Knowledge Requirements

  • Document if block requires more advanced knowledge than typical blocks
  • Provide appropriate warnings or prerequisites in README

🔍 Search the handbook

All pages