Automattic / Automattic/markdown-database-integration

Architecture: punt all git concerns to DMC GitSync

Open
#61 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PHP
Stars
5
Forks
1
Avg merge
2h 38m
Merged PRs (30d)
155

Description

## Statement

**Markdown Database Integration should not implement git operations.** All git concerns (remotes, pull, push, bind, auth, conflict resolution) belong in the separate [Data Machine Code GitSync](https://github.com/Extra-Chill/data-machine-code) module, which shipped this layer on 2026-04-20.

This issue exists to formalize that boundary so future contributors don't reach for git primitives inside MDI.

## Layering

```
┌─────────────────────────────────────────────────┐
│ DMC GitSync │
│ bind / pull / push / submit / status / policy │ ← ALL git concerns
│ GitHub Contents + Git Data APIs │
│ (no shell, no git binary, no .git/ directory) │
└─────────────────────────────────────────────────┘

│ points at wp-content/markdown/

┌─────────────────────────────────────────────────┐
│ Markdown Database Integration │
│ WP post ↔ .md file on disk │ ← filesystem stops here
│ frontmatter / loader / write engine / index │
└─────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────┐
│ WordPress (posts, meta, options) │
└─────────────────────────────────────────────────┘
```

- **MDI's job:** WordPress post ↔ markdown file on disk. Full stop.
- **GitSync's job:** markdown file on disk ↔ upstream git repo.
- **Integration:** GitSync writes files; MDI notices (via file-watching, not git).

## What stays in MDI

- File watching / filesystem reactivity — detecting new or changed `.md` files and rehydrating the post index. This is incremental-sync plumbing, not a git concern.
- Frontmatter round-trip, slug derivation, ID assignment (see #42).
- The markdown ↔ block conversion pipeline.

## What moves out (or was never MDI's in the first place)

- `git commit` / `git push` / `git pull` / `git status` — DMC GitSync.
- Remote repo configuration and auth — DMC GitSync.
- Branch / worktree management — DMC GitSync.
- Conflict resolution semantics — DMC GitSync.
- PR creation for wiki-content syncs — DMC GitSync's `submit` ability.

## Why this matters

MDI must work identically across environments:

- Self-hosted with DMC + GitSync installed
- Studio local dev (symlinked MDI checkouts, no DMC)
- WP.com / VIP (no drop-ins, no DMC)
- Minimal installs with only MDI

Coupling MDI to git primitives would produce two code paths — one for "git is available" and one for "git isn't" — which is exactly the `class_exists()` branching the ecosystem explicitly forbids inside feature flows. Users on managed hosts would get a subtly different MDI than self-hosters.

Keeping git in GitSync makes MDI portable, and makes GitSync swappable (the same `markdown/` directory could be synced by any alternative implementation — Meilisearch-based sync, inotify-based local mirror, a Dropbox-style agent, etc.).

## Action items

- [ ] Confirm current MDI roadmap does not list "git auto-commit" or similar. If it does, remove it.
- [ ] If any code inside MDI currently shells out to `git`, extract it. (Spot-check says no, but double-check.)
- [ ] Future "file watching" work (fs_events, inotify, polling) lands in MDI. Future "sync this dir with GitHub" work lands in DMC GitSync.

## References

- DMC GitSync shipped: [data-machine-code#38](https://github.com/Extra-Chill/data-machine-code/issues/38), PR [#42](https://github.com/Extra-Chill/data-machine-code/pull/42), [#43](https://github.com/Extra-Chill/data-machine-code/pull/43)
- DMC GitSync is API-first (GitHub Contents + Git Data APIs) — works on WP.com Business, WP Engine, Pantheon, etc.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.