# Keeping up with WordPress

WordPress ships security releases, and a fork that cannot take them quickly is
a liability rather than a project. This page is how Sirius Press takes them.

---

## The arrangement

WordPress lives in this repository, at `wordpress/`, as a **git subtree**. The
fork's own change sits on top of it as an ordinary commit.

Three pieces make that work:

| | |
|---|---|
| `wordpress/` | The vendored tree, patched. This is what gets built and shipped. |
| `sirius-press/wordpress-upstream` | A branch holding **pristine** upstream releases, one commit each, never edited. The other side of the merge. |
| `patches/` | A readable record of what the fork changes in core. Generated, not maintained. |

The entire core diff is **one file, 75 lines**: `wp-admin/install.php`, the
setup wizard. Everything else Sirius Press does is plugins and hooks.

### Why a subtree and not a patch series

Because a three-way merge understands something a patch does not. When
upstream edits lines near the fork's change, `git subtree merge` merges them
and moves on; `patch` either applies with fuzz and hopes, or fails and hands
you the job of re-deriving the change by hand. A conflict from the merge is
resolved once, in the file, and stays resolved — the next release merges
against the resolution.

The cost is repository size: WordPress is about 149 MB and 3,800 files. That
is the price of a fork that can take a security release in a minute, and it is
the right trade for a project whose whole argument is that it should outlive
its maintainers' attention.

---

## Taking a new release

```bash
tools/update-wordpress.sh 7.1.2
```

It downloads the release, checks it against the SHA-1 wordpress.org publishes,
imports the pristine tree onto `sirius-press/wordpress-upstream`, and merges
that branch into `wordpress/`. Then it updates `tools/wordpress.lock` and
regenerates `patches/`.

Two outcomes.

**Clean.** The merge went through. Run the tests, build, commit. Usually a
minute of work.

**Conflicted.** Upstream changed the same lines the fork changes — in
practice, `wp-admin/install.php`. Git leaves the conflict in the file:

```bash
git status
$EDITOR wordpress/wp-admin/install.php
git add wordpress/wp-admin/install.php
git commit
tools/refresh-patches.sh
```

Then set `WP_VERSION`, `WP_URL`, `WP_SHA256` and `WP_SHA1` in
`tools/wordpress.lock` by hand, since the script stopped before it got there.

Either way the fork is **not broken while you work**: the merge is in your
working tree, and until you commit it, `wordpress/` still holds the last
version that worked.

---

## After any bump

```bash
tests/run.sh
tools/build.sh
```

The suite does not test core, but it tests every assumption the fork makes
about it. Then walk through `wp-admin/install.php` once in a browser — the
setup wizard is the only patched file, so it is the only thing an upstream
change can break in a way the tests would miss.
[testing.md](testing.md) has a recipe for a throwaway instance that needs no
database server.

---

## Keeping `patches/` honest

`patches/` is documentation. It answers the question anyone auditing this fork
asks first — *what exactly did you change inside WordPress?* — in a minute,
which `git log wordpress/` cannot, because that log is mostly upstream
imports.

It is generated from the tree, never edited:

```bash
tools/refresh-patches.sh          # rewrite it
tools/refresh-patches.sh --check  # fail if it has drifted (for CI)
```

Generated documentation stays true. A hand-maintained record of a fork's core
diff drifts, and a stale one is worse than none, because people trust it.

---

## Changing core yourself

Edit the file under `wordpress/` and commit it like any other change. The next
upstream merge will three-way it.

Before you do: check whether a plugin hook can carry the change instead. Every
line added to `wordpress/` is a line that can conflict with upstream forever,
and the reason this fork's merges are cheap is that there are only 75 of them.
The registration form, the password-reset page and the mail pipeline were all
replaced from plugins precisely so they would never appear in this directory.

---

## Where this repository lives

`code.silentmode.st/silentmode/sirius-press` is a **mirror**. Sirius Press is
developed inside the Silent Mode monorepo and split out with
`scripts/push-split.sh`, which force-pushes `master` each time. History on the
forge is real — file blame points at the actual commits — but it is rewritten
on every push, so a pull request against it will not survive.

What that means in practice:

- **Silent Mode takes upstream releases in the monorepo**, where the subtree's
  merge history is intact, and the result is mirrored here.
- **A downstream fork** that clones from the forge and wants to bump WordPress
  itself should treat its clone as the source of truth from that point on and
  stop pulling the mirror, because the next mirror push will not merge with
  its work.

Patches and bug reports are welcome as issues; code is easiest to take as a
diff rather than as a branch.

---

## If the upstream branch is missing

A clone made with `--single-branch` will not have
`sirius-press/wordpress-upstream`, and `tools/update-wordpress.sh` will say so
rather than guessing. Fetch it:

```bash
git fetch origin sirius-press/wordpress-upstream:sirius-press/wordpress-upstream
```

Building and running do not need it — only taking a new upstream release does.