Automattic / Automattic/php-toolkit

Allow plugins to register Push MD content adapters

Ouverte
#79 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
PHP
Étoiles
22
Forks
5
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

## Problem

Push MD hardcodes the WordPress entities it exports and imports. Markdown post types begin with `post` and `page`, while Guidelines, raw block entities, and Global Styles are added through private type-specific branches in `Push_MD_Plugin`.

Current source: [`Push_MD_Plugin::$supported_post_types` and `get_supported_post_types()`](https://github.com/Automattic/php-toolkit/blob/02e19f0559d48359ce62183e993e722362732050/plugins/push-md/class-push-md-plugin.php#L53-L122).

A plugin cannot register its own content model with Push MD without modifying Push MD itself. Adding a post-type-name filter alone would be unsafe: path identity, hierarchy, metadata, taxonomy relationships, import validation, capabilities, branch previews, seeding, and collision handling must use the same contract.

## Use case

The WP Docs proof of concept needs a private, hierarchical documentation post type to round-trip through Push MD while WordPress remains the content source of truth. Collections and topics must retain deterministic taxonomy relationships, and the documentation hierarchy must map to stable repository paths.

This should be solved as a generic Push MD extension point rather than a WP Docs special case.

## Proposed direction

Add a fail-closed content-adapter registry that third-party plugins can populate before Push MD seeds or synchronizes its repository.

An adapter should define enough behavior for Push MD to apply one consistent contract across:

- entity discovery and supported statuses;
- stable path and identity mapping;
- serialization and parsing;
- hierarchy and dependency validation;
- taxonomy or other declared metadata relationships;
- create, update, move, and trash planning;
- read/edit/create/delete capability checks;
- branch preview projection where supported.

Push MD should continue to own Git protocol handling, stale-state checks, whole-push validation, path safety, collision rejection, atomic planning, repository persistence, and authentication. Adapters provide WordPress entity semantics, not alternate Git behavior.

The built-in post/page behavior should use the same registry where practical so extension behavior cannot drift from core behavior.

## Acceptance criteria

1. A separate plugin can register a Markdown-backed hierarchical CPT without editing Push MD source.
2. Registration rejects duplicate adapter IDs, duplicate post types, reserved or colliding paths, invalid callbacks, and registration after the registry is frozen.
3. Seeder counts, WordPress export, path parsing, push planning/application, permission checks, and branch previews resolve through the registered adapter contract.
4. All incoming changes are parsed and validated before the first WordPress mutation; an adapter failure rejects the complete push.
5. Deterministic tests cover clone, update, create, hierarchy change, taxonomy relationships, collision rejection, stale push rejection, and trash behavior for a plugin-defined CPT.
6. Existing posts, pages, templates, template parts, navigation, Global Styles, and Guidelines retain their current repository paths and behavior.
7. Public extension documentation includes a minimal third-party adapter example and lifecycle timing.

## Consumer

Tracked WP Docs work: [chubes4/wp-docs#19](https://github.com/chubes4/wp-docs/issues/19).

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Piste de recherche

Commencez par lire Push_MD_Plugin::$supported_post_types et get_supported_post_types() dans plugins/push-md/class-push-md-plugin.php, puis suivez les flux existants de post/page et des autres entités mentionnés dans les critères d’acceptation. Définissez le contrat de l’adaptateur et les limites du registre avant l’implémentation ; le travail est terminé lorsqu’un plugin séparé peut effectuer un round-trip d’un CPT hiérarchique tout en préservant la validation, les permissions, les chemins, les prévisualisations et le comportement des entités existantes.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
php, wordpress
Domaine
backend, content
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.