Update the repository name in user-facing links and user agents - #344
Merged
juanmaguitar merged 2 commits intoAug 14, 2026
Merged
Conversation
juanmaguitar
added a commit
that referenced
this pull request
Aug 14, 2026
## Why
`v1.0.0` is published, but the repository's front page still describes
the app as it was at
`v0.1.x`: a thing that sets up a development environment with no
prerequisites, full stop. Nothing
that 1.0 is actually about appears on it — linking a Trac ticket,
reading its facts, applying the
pull requests and patches already on it, holding work for several
tickets in one site, debugging,
or sending a change back as a pull request, a Trac attachment or a
mentor handoff.
`### Why` had the same problem in argument form: it makes the case
against setup friction, which is
the wall `v0.1.x` removed, and stops there.
Someone arriving from the Make announcement or from the release page
reads this file first. It was
underselling the release they had just heard about.
## What changes
**`README.md`.** The top of the file only; every section about
contributing to *this repository* —
`Build from source`, `App icon`, `Why Electron?`, `Ideas and future
work`, `Download stats`,
`Contributing`, `License` — is current and untouched.
- The description paragraph now covers the whole loop rather than only
setup, including the two
guarantees that are easy to miss and hard to re-derive: nothing
installed on the host, and no push
credential written to disk.
- `### Why` keeps the Contributor-Day setup argument as it was and adds
the second wall: a newcomer
with a running environment still has to find the existing patch, get it
into the checkout,
understand a failed apply, and work out that WordPress reviews on Trac
but takes pull requests on
GitHub.
- A new **What you can do with it** section: seven capabilities, each
linking the guide page that
already documents it, so the README stays a map and the guide stays the
manual.
- Both YouTube blocks are removed. They show the pre-1.0 interface, and
the second one demonstrates
the patch screen that 1.0 reworked. Their thumbnails,
`docs/setup-start.png` and
`docs/create-patch.png`, are deleted with them — the README was their
only reference.
- One current screenshot near the top, `site-view.png`, served from the
docs site. **This was not
asked for:** removing two images and adding none leaves the page worse,
and this is the image the
release notes and the announcement both open with. Say so if you would
rather the README carried
no image.
**`package.json`.** `description` was `Electron app to setup WordPress
develop structure and run npm
install`. electron-builder carries this into the packaged application's
metadata, so it is
user-visible, and it described a subset of `v0.1.x`. It now describes
the app. No other field
changes.
**Not in this PR, for JuanMa to apply in Settings:** the GitHub
repository description is still
"An experiment to explore an easy to install core WordPress development
environment app". Proposed
replacement, same sentence as the new `package.json` description:
> Desktop app that sets up a WordPress core development environment with
no prerequisites, applies
> the work already on a Trac ticket, and submits a contribution back.
## How to test this
Platforms: any; this is documentation and package metadata.
1. Run `npm run lint` and `npm test`.
- Expected: lint succeeds and all 1,027 tests pass.
2. Run `npm run docs:build`.
- Expected: the VitePress build completes, confirming nothing under
`docs/` referenced the two
deleted images. It does **not** validate the README's links: `README.md`
is not part of the
docs source tree, and the links are absolute external URLs, which
`ignoreDeadLinks` does not
reach. Step 3 is what checks those.
3. From the repository root, confirm every guide page the README links
actually exists:
```bash
for p in $(grep -o 'contributor-toolkit/guide/[a-z-]*' README.md | sed
's|.*/guide/||' | sort -u); do
test -f "docs/guide/$p.md" && echo "ok $p" || echo "MISSING $p"
done
```
- Expected: 16 lines, all `ok`.
4. View `README.md` rendered on this branch on GitHub.
- Expected: the three badges load, the screenshot loads, and every link
in **What you can do with
it** opens a real guide page rather than a 404.
5. Run `node -p "require('./package.json').description"`.
- Expected: the new sentence.
**What must not have happened:** no source file, workflow or build
configuration in the diff; the
version and every dependency unchanged.
## Risks and limitations
The main risk in a change like this is a claim that reads well and is
not true. Every capability
listed was checked against the guide page it links and against the
shipped behaviour rather than
against memory; the review below covers that specifically.
The screenshot is hotlinked from the docs site rather than committed, so
it tracks whatever the
shots harness last published. That keeps it from going stale silently,
at the cost of depending on
Pages being up — the same trade the release notes make.
The new `description` is 163 characters. It reaches the AppImage and deb
`.desktop` `Comment`, the
deb control `Description` and the snap `description`; no length ceiling
is hit and no build breaks.
Snap's 78-character limit applies to `summary`, which electron-builder
fills from `productName`.
One cosmetic consequence: Debian's `lintian` warns
`description-too-long` on a synopsis over 80
characters, so the `.deb` picks up a warning it did not have before. Not
a build failure, not
user-visible.
## Related
Follows `v1.0.0` (#343, #344).
---
<details>
<summary>Review outcome (required — see AGENTS.md)</summary>
`0 [fix here] · 0 [follow-up]`. No findings across architecture,
security, performance,
cross-platform or tests. `npm run lint`, `npm test` (1,027/1,027) and
`npm run docs:build` pass.
Because the risk in this change is a claim that reads well and is false,
the review was pointed at
the claims themselves. Each was traced to code, not to memory:
- *no push credential written to disk* — the token exists only as
`githubToken` in `src/main.js:775`,
cleared at `:783`, passed by value into `src/github-pr.cjs`. No
`store.set`, no keychain, no file
write.
- *says which regions failed and why, and leaves the checkout untouched*
— `src/patch-apply.js`
validates before writing. The one path that does write is a rollback
after a disk error mid-write
(`src/patch-apply.js:526-530`), which is a write failure rather than a
patch that will not apply;
the guide draws the line in the same place.
- *each ticket gets its own branch inside the site* —
`src/ticket-branches.js:4-23`.
- *fatals surfaced instead of hidden behind the recovery screen* —
`src/wp-debug-constants.js:47`
sets `WP_DISABLE_FATAL_ERROR_HANDLER: true`.
- *a terminal using the Node.js runtime the app bundles* —
`src/script-runner.js:26,36` spawn
`process.execPath`; `src/npm-runner.js:88` sets
`ELECTRON_RUN_AS_NODE=1`.
- *keeps your name on the work* — `src/patch-provenance.cjs`.
- *fetching only what changed* — `src/trunk-update.js:269-273`, `depth:
1`.
- *with a rebuild when one is needed* — conditional rather than
decorative:
`src/renderer/update-plan.cjs:144` skips the build when the watcher is
live.
- The Trac field list maps 1:1 onto `src/trac-ticket-info.cjs:133-142`.
Also verified: no doc page, workflow, issue template or
`scripts/screenshots/` entry referenced
either deleted PNG or either YouTube URL; every guide target exists; and
the extensionless link form
is what the file already used on `trunk` and what Pages resolves through
its `.html` fallback.
The review corrected one claim in this PR's own test plan: `npm run
docs:build` does not validate
the README's links, because `README.md` is not in the docs source tree
and the links are absolute
external URLs. Step 2 above has been rewritten to say so, and step 3 is
what actually checks them.
</details>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The repository was renamed from
experimental-wp-dev-envtocontributor-toolkit. GitHub redirectsthe old URLs, so nothing is broken — which is exactly why the stale references survived. But they
are user-facing, and 1.0 is the release that gets read: the README badges are the first thing on the
repository page, and two of them are shields.io images built from the repository name rather than
plain links.
#343 fixed
package.json. This is the rest of it.What changes
Nine occurrences across six files, all of them
WordPress/experimental-wp-dev-env→WordPress/contributor-toolkit:README.md— the unit-tests, latest-release and downloads badges (image source and link target).STATS.md— the two links to themetricsorphan branch and todownloads.csvon it..github/ISSUE_TEMPLATE/Bug_report.yml— the "search existing issues" URL shown to a reporter..github/ISSUE_TEMPLATE/installation-bug.yml— the download-source placeholder.src/trac-view.jsandsrc/github-http.cjs— the+https://…project URL inside theWordPress-Contributor-Toolkituser agent sent to Trac and to the GitHub API. The identifyingprefix is unchanged; only the URL a server operator would follow moves.
Deliberately kept: the old name in the comments at
docs/.vitepress/config.mjs:9and.github/workflows/docs.yml:14. Both describe the rename itself and explain why the Pages base pathis derived at run time rather than hardcoded, so the old name is the point of the sentence. The
workflow comment did still say the repository "is being renamed"; it now matches the VitePress one
and says the rename has already happened, which is also the accurate reason to keep deriving the
path — the next rename, not this one.
How to test this
Platforms: any; this is text and metadata.
Starting state: this branch checked out with dependencies installed.
grep -rn "experimental-wp-dev-env" . | grep -v node_modules | grep -v "^./.git".README.mdon this branch and confirm all three badges load an image ratherthan a broken-image icon, and that clicking each lands on the
contributor-toolkitrepository.STATS.mdand confirm they reach themetricsbranch anddownloads.csv.URL in the bug-report description and the corrected placeholder in the installation-bug form.
npm run lintandnpm test.What must not have happened: the
WordPress-Contributor-Toolkitprefix of either user agent mustbe unchanged —
test/github-http.test.cjs:56asserts on it, and Trac's proof-of-work session isidentified by it.
Risks and limitations
The user-agent change is the only line that leaves the machine. Its value is not persisted, not used
as a cache key and not part of the Trac session partition (
persist:trac), so an existing site'scleared proof-of-work challenge survives the change.
Nothing here can be verified from the diff alone for the badges: shields.io builds them server-side
from the repository name, so they can only be confirmed on the rendered page.
Related
Stacked on #343, which fixed the same stale name in
package.jsonand added the missingrepositoryandbugsfields.Review outcome (required — see AGENTS.md)
0 [fix here] · 1 [follow-up, fixed here]. No findings across architecture, security, performance,cross-platform or tests.
npm run lintandnpm test(1,027/1,027) pass.The follow-up was the tense of the
docs.ymlcomment, which is in this PR's own subject matter andso was fixed here rather than deferred.
Verified as part of the review: no test, fixture or snapshot pins the old user-agent string — the
only assertion is
test/github-http.test.cjs:56on theWordPress-Contributor-Toolkitprefix, andtest/trac-view.test.cjs:39stubssetUserAgent()without inspecting its argument. Neitherconstant is value-sensitive:
src/github-http.cjs:91only sets a request header, and the Tracpartition is the literal
'persist:trac'(src/trac-view.js:27), not derived from the user agent,so no cleared proof-of-work session is orphaned.
download-stats.yml:68already uses$GITHUB_REPOSITORY, so the metrics branch keeps writing under whatever the repository is called.