Skip to content

Bump version to 1.0.0 and point homepage at the docs site - #343

Merged
juanmaguitar merged 3 commits into
trunkfrom
juanmaguitar/Release-v1.0
Aug 14, 2026
Merged

Bump version to 1.0.0 and point homepage at the docs site#343
juanmaguitar merged 3 commits into
trunkfrom
juanmaguitar/Release-v1.0

Conversation

@juanmaguitar

@juanmaguitar juanmaguitar commented Aug 14, 2026

Copy link
Copy Markdown
Collaborator

Why

v1.0.0-rc.2 shipped on 13 August as the second release candidate. Testing it on Windows found one
behaviour bug, now fixed on trunk (#342: the CRLF workaround wrote core.autocrlf into every
managed 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 must
move before its tag and artifacts are created, because electron-builder derives artifact names
from package.json.

Two metadata corrections, no application behavior change.

What changes

The version. All three package-version fields in package.json and package-lock.json move
together from 1.0.0-rc.2 to 1.0.0. No dependency versions change.

homepage. It still pointed at https://github.com/WordPress/experimental-wp-dev-env, the
repository'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 deployment
docs/.vitepress/config.mjs builds with base: '/contributor-toolkit/'. Shipping a 1.0 whose
package metadata names the old repository is the reason to fix it now rather than later.

repository and bugs, which did not exist. homepage was the only field naming the
repository, 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-builder derives artifact names from package.json, producing:

  • wordpress-contributor-toolkit-1.0.0-mac-arm64.dmg
  • wordpress-contributor-toolkit-1.0.0-win-x64.exe
  • wordpress-contributor-toolkit-1.0.0-linux-x86_64.AppImage

How to test this

Platforms: any; this is package metadata and is platform-independent.

Starting state: this branch checked out with dependencies installed.

  1. Run node -p "require('./package.json').version".
    • Expected: 1.0.0.
  2. Run node -e "const p=require('./package-lock.json'); console.log(p.version, p.packages[''].version)".
    • Expected: 1.0.0 1.0.0.
  3. Run node -p "require('./package.json').homepage".
    • Expected: https://wordpress.github.io/contributor-toolkit/, and opening it in a browser
      reaches the toolkit's documentation site rather than a 404.
  4. Run npm run lint and npm test.
    • Expected: lint succeeds and all 1,027 tests pass.

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.0 rather than to a third release candidate: the only behaviour
change 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 v prefix; package metadata does
not.

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), and git diff --check pass.
The stale homepage was itself the review's one observation, and is fixed in this PR.

Nothing reads homepage at runtime, and electron-builder has no publish block that would
derive 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 the
app version (src/logging.js:78 reads it via app.getVersion()); the lockfile diff carries no
dependency or integrity churn; electron-builder is prerelease-agnostic — the artifact template at
package.json:30 is …-${version}-${os}-${arch}.${ext} and the repo has no publish block, no
channel 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.vue resolves
releases/latest, which the GitHub API defines as excluding pre-releases. Since v0.1.2 the button
has 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-version keeps package.json, the lockfile root version and
packages[""].version synchronized. The diff was checked to confirm those are the only changed
values.

@juanmaguitar juanmaguitar changed the title Bump version to 1.0.0 Bump version to 1.0.0 and point homepage at the docs site Aug 14, 2026
@juanmaguitar

Copy link
Copy Markdown
Collaborator Author

Stacked follow-up: #344 clears the same stale repository name from the README badges, STATS.md, the two issue templates and the two USER_AGENT constants. Its base is this branch, so merge this one first.

@juanmaguitar
juanmaguitar merged commit a006f59 into trunk Aug 14, 2026
3 checks passed
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>
@juanmaguitar
juanmaguitar deleted the juanmaguitar/Release-v1.0 branch August 21, 2026 09:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant