961cb108ca
The subtree is in place, so everything that used to fetch and patch core at
build time now just copies it.
tools/build.sh copies wordpress/ — no download, no checksum step,
because there is nothing to fetch and nothing to
trust that is not already in the repository
docker/Dockerfile COPY wordpress/ instead of curl + sha256 + patch;
the build args and the `patch` package are gone
docker-compose.yml no WP_VERSION / WP_URL / WP_SHA256 to keep in step
tools/update-wordpress.sh is rewritten around what the subtree makes
possible. It imports the pristine release onto sirius-press/wordpress-upstream
and then `git subtree merge`s that branch, which three-way merges upstream
against the fork's own commit. A patch either applies with fuzz and hopes or
fails and leaves you re-deriving the change by hand; a merge conflict is
resolved once, in the file, and the next release merges against the
resolution.
patches/ survives as documentation rather than mechanism, and is now
generated: tools/refresh-patches.sh diffs the subtree against the pristine
import and rewrites the directory, with --check for CI. It answers the
question anyone auditing a 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. Generated documentation stays true; a
hand-maintained record of a core diff drifts, and a stale one is worse than
none because people trust it.
One test change worth noting: the syntax sweep no longer walks all of
wordpress/. It lints the fork's own PHP plus every core file patches/ says
the fork touches, which keeps the suite at seven seconds instead of a minute
while still covering the only core file that can break.
134 lines
4.5 KiB
Markdown
134 lines
4.5 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 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.
|