Bump version to 1.0.0 and point homepage at the docs site - #343
Merged
Conversation
Collaborator
Author
|
Stacked follow-up: #344 clears the same stale repository name from the README badges, |
juanmaguitar
added a commit
that referenced
this pull request
Aug 14, 2026
> **Stacked on #343.** Base branch is `juanmaguitar/Release-v1.0`, not `trunk`. Merge #343 first. ## Why The repository was renamed from `experimental-wp-dev-env` to `contributor-toolkit`. GitHub redirects the 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 the `metrics` orphan branch and to `downloads.csv` on 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.js` and `src/github-http.cjs` — the `+https://…` project URL inside the `WordPress-Contributor-Toolkit` user agent sent to Trac and to the GitHub API. The identifying prefix is unchanged; only the URL a server operator would follow moves. **Deliberately kept:** the old name in the comments at `docs/.vitepress/config.mjs:9` and `.github/workflows/docs.yml:14`. Both describe the rename itself and explain why the Pages base path is 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. 1. Run `grep -rn "experimental-wp-dev-env" . | grep -v node_modules | grep -v "^./.git"`. - Expected: exactly two hits, the two explanatory comments named above. 2. Open the rendered `README.md` on this branch and confirm all three badges load an image rather than a broken-image icon, and that clicking each lands on the `contributor-toolkit` repository. 3. Follow both links in `STATS.md` and confirm they reach the `metrics` branch and `downloads.csv`. 4. Open **New issue** on this branch's fork and confirm both templates render, with the corrected URL in the bug-report description and the corrected placeholder in the installation-bug form. 5. Run `npm run lint` and `npm test`. - Expected: lint succeeds and all 1,027 tests pass. **What must not have happened:** the `WordPress-Contributor-Toolkit` prefix of either user agent must be unchanged — `test/github-http.test.cjs:56` asserts on it, and Trac's proof-of-work session is identified 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's cleared 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.json` and added the missing `repository` and `bugs` fields. --- <details> <summary>Review outcome (required — see AGENTS.md)</summary> `0 [fix here] · 1 [follow-up, fixed here]`. No findings across architecture, security, performance, cross-platform or tests. `npm run lint` and `npm test` (1,027/1,027) pass. The follow-up was the tense of the `docs.yml` comment, which is in this PR's own subject matter and so 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:56` on the `WordPress-Contributor-Toolkit` prefix, and `test/trac-view.test.cjs:39` stubs `setUserAgent()` without inspecting its argument. Neither constant is value-sensitive: `src/github-http.cjs:91` only sets a request header, and the Trac partition 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:68` already uses `$GITHUB_REPOSITORY`, so the metrics branch keeps writing under whatever the repository is called. </details>
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
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
v1.0.0-rc.2shipped on 13 August as the second release candidate. Testing it on Windows found onebehaviour bug, now fixed on
trunk(#342: the CRLF workaround wrotecore.autocrlfinto everymanaged repository's config, on every platform). The other four commits since that tag are
documentation and guide screenshots (#336, #337, #339).
Nothing else is outstanding, so the next version is the stable
1.0.0. The package version mustmove before its tag and artifacts are created, because
electron-builderderives artifact namesfrom
package.json.Two metadata corrections, no application behavior change.
What changes
The version. All three package-version fields in
package.jsonandpackage-lock.jsonmovetogether from
1.0.0-rc.2to1.0.0. No dependency versions change.homepage. It still pointed athttps://github.com/WordPress/experimental-wp-dev-env, therepository's name before the rename, and it pointed at a repository rather than at a place a
contributor would want to land. It now points at the documentation site,
https://wordpress.github.io/contributor-toolkit/— the Pages deploymentdocs/.vitepress/config.mjsbuilds withbase: '/contributor-toolkit/'. Shipping a 1.0 whosepackage metadata names the old repository is the reason to fix it now rather than later.
repositoryandbugs, which did not exist.homepagewas the only field naming therepository, so pointing it at the documentation site would have left the package metadata with no
reference to the repository at all. Both fields are now present and name
contributor-toolkit,which is where that information belongs.
electron-builderderives artifact names frompackage.json, producing:wordpress-contributor-toolkit-1.0.0-mac-arm64.dmgwordpress-contributor-toolkit-1.0.0-win-x64.exewordpress-contributor-toolkit-1.0.0-linux-x86_64.AppImageHow to test this
Platforms: any; this is package metadata and is platform-independent.
Starting state: this branch checked out with dependencies installed.
node -p "require('./package.json').version".1.0.0.node -e "const p=require('./package-lock.json'); console.log(p.version, p.packages[''].version)".1.0.0 1.0.0.node -p "require('./package.json').homepage".https://wordpress.github.io/contributor-toolkit/, and opening it in a browserreaches the toolkit's documentation site rather than a 404.
npm run lintandnpm test.What must not have happened: dependency versions and resolved packages must remain unchanged; no
source, documentation, workflow, or build configuration file should be in the diff.
Risks and limitations
No user-visible behavior changed, so there is no desktop flow or screenshot to test by hand. The
signed artifacts will only exist after this PR lands and the release build runs.
Dropping the pre-release suffix means the resulting GitHub release is the first one to take the
Latest badge from
v0.1.2.Related
Follow-up to #335. Ships the fixes in #342, #336, #337 and #339 as the stable 1.0.
Design decisions and alternatives considered
The version goes straight to
1.0.0rather than to a third release candidate: the only behaviourchange since rc.2 is #342, which was itself the finding rc.2 existed to surface, and it has been
verified on Windows. The release tag will add the conventional
vprefix; package metadata doesnot.
Review outcome (required — see AGENTS.md)
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), andgit diff --checkpass.The stale
homepagewas itself the review's one observation, and is fixed in this PR.Nothing reads
homepageat runtime, andelectron-builderhas nopublishblock that wouldderive an update feed from it, so the change is metadata only.
Verified as part of the review: no source, script, docs,
.buildkite/or workflow file embeds theapp version (
src/logging.js:78reads it viaapp.getVersion()); the lockfile diff carries nodependency or integrity churn;
electron-builderis prerelease-agnostic — the artifact template atpackage.json:30is…-${version}-${os}-${arch}.${ext}and the repo has nopublishblock, nochannel and no auto-updater, so dropping the suffix only shortens the filenames; and nothing in CI
keys off a tag or version pattern.
One consequence worth stating:
docs/.vitepress/theme/DownloadButton.vueresolvesreleases/latest, which the GitHub API defines as excluding pre-releases. Sincev0.1.2the buttonhas been falling back to the Releases page for everyone. Publishing 1.0.0 as a non-prerelease is
what makes it resolve a real asset again.
Implementation notes
npm version 1.0.0 --no-git-tag-versionkeepspackage.json, the lockfile rootversionandpackages[""].versionsynchronized. The diff was checked to confirm those are the only changedvalues.