WordPress-iOS: a Rake-driven setup documented down to the client secret

The Makefile has two targets and never appears in the README

The checked-in Makefile is short enough to quote in full, and it declares exactly two phony targets. One prints a target list by grepping the Makefile itself for lines carrying a `##` comment. The other runs a shell script that downloads and caches the Gutenberg XCFrameworks:

.PHONY: help dependencies

help: ## Show available targets
	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk -F ':.*## ' '{printf "  %-20s %s\n", $$1, $$2}'

dependencies: ## Download and cache Gutenberg XCFrameworks
	./Scripts/download-gutenberg-xcframeworks.sh

Two things follow from those eleven lines. The help target greps `$(MAKEFILE_LIST)`, so it can only ever report targets living in this file, which means `make help` will list two entries while the documented workflow has at least four steps. And the README never mentions make at all: every command it gives is a Rake task. The dependency work appears in both files, described differently, with the Makefile version caching XCFrameworks and the Rake version described as configuring third party tools. Whether one calls the other is not stated.

Four rake tasks, and init:oss is the one nobody describes

The documented setup is a chain of four Rake tasks. `rake dependencies` configures or updates the third party tools. `rake init:oss` configures the local machine and the app so that they can run and log into WordPress.com. `rake xcode` opens the workspace, and the Configuration Details section adds that it also makes sure any dependencies are ready before launching Xcode. `rake credentials:setup` prompts for a Client ID and a Client Secret.

Three of those four arrive with a sentence of explanation. `init:oss` does not, and its suffix implies a sibling task for a build that is not the open source one, a task named nowhere in the documentation. A reader who needs that variant has no documented first command. The Configuration Details section exists precisely because steps sometimes have to be run again, and it covers re-running `rake dependencies` and `rake xcode` without ever returning to `init:oss`.

Two version pins, and only one comes with a tool recommendation

The build instructions hand their version requirements to two dotfiles. The minimum Xcode version lives in `.xcode-version`, and the Ruby version lives in `.ruby-version`; for the second, the README suggests a tool like rbenv and then tells you to run `rbenv install` in the repository to match. Xcode gets no equivalent suggestion. Step one is a download link to Apple's developer site and a pointer at the file, which leaves the reader to install and update the IDE by hand.

Minimum is also doing quiet work in that first line. The file records a floor, and nothing states which Xcode version the current code is written against or what breaks above it. A clean checkout needs more than the two pins: there is a `Package.resolved` next to the SwiftPM manifest and a `Modules/` directory, so dependency resolution sits between the Ruby toolchain and the first successful build, and the README's chain never names that step.

One application registration means one account can log in

The README states the same restriction twice, and sets it in bold the second time: you can only log in with the WordPress.com account that was used to create the WordPress application. The mechanism sits right next to it. The Client ID and Client Secret come out of the application you registered, and those two values are what authenticate the API calls the app makes, so the account holding the registration is the account that gets in.

The consequence for a team is direct. The credential pair is not a shared project secret to be pasted onto a build machine, because a shared pair would log everyone in as one person. Each developer who wants to reach their own dashboard has to register their own application in the WordPress.com applications manager, and the documentation offers no path for a second account to reuse a first account's registration. The account in question is the one signed up through the user signup page, not a site on a domain.

Three required fields the app never uses

Registering the application asks for a Website URL, for Redirect URLs and for Javascript Origins. The documentation's own comment on those fields is that they are required but not used for the mobile apps, and that Redirect URLs should be set to `https://localhost`. A native client that follows no browser redirect has no local server to return to, which is the reason the values do not matter, and the README is upfront about it.

What is untidy is that the two walkthroughs disagree about the form itself. The Getting Started section names Website URL, Redirect URLs and Type, and sets Type to Native. The Setup Credentials section names Website URL, Redirect URLs and Javascript Origins, then says to select "Native client" for the application type. Same registration screen, two different field lists and two different labels for one dropdown value. The first walkthrough also tells you to click "Create" and then "Update", a step the second one never repeats.

Agent files, three formatters and a secrets directory, none of them documented

The top level is where this repository stops looking like a two task build. Next to the SwiftPM manifest and the `Modules/` directory sit `AGENTS.md` and `CLAUDE.md`, plus `.agents/` and `.claude/` directories, which read as instructions written for coding agents rather than for compilers. Then there are three separate style configurations, `.swift-format`, `.swiftlint.yml` and `.clang-format`, a Dangerfile for reviewing changes, a `fastlane/` directory, a `.buildkite/` directory, CODEOWNERS, a `.a8c-secrets/` directory, and a `.configure` file with `.configure-files/` beside it.

The build instructions cover cloning, credentials and opening Xcode, and stop there. None of that machinery is mentioned, so it is discoverable only by reading the tree. A `.xctool-args` file and a `BuildTools/` directory at the same level point at a command line build path that the documentation never describes, and `RELEASE-NOTES.txt` sits beside the README without a line explaining when to read it.

27.3.0.0 shipped a week before 27.3

The release list runs backwards at the fine end. Version 27.2 was published on 2026-08-30, then 27.3.0.0 on 2026-09-21, and then 27.3 on 2026-09-28, so a four part build number appeared a week before the shorter version that should contain it. The last push to trunk was 2026-10-01, three days after that 27.3 tag. Nothing in the README explains the two numbering schemes, and the top level keeps a `RELEASE-NOTES.txt` that the build instructions never point at.

The other gap costs a new contributor more time. There is a `Tests/` directory, a Dangerfile, a `.buildkite/` directory and a CONTRIBUTING.md, and the documented path ends at compiling to an iOS device or simulator and logging in. No test command, no continuous integration badge, and no description of what has to pass before a change lands. The security route is the one exception, since the README does name an address for private disclosure and asks for time to respond before anything becomes public.

Editorial conclusion

The setup path is documented well enough to follow and thin enough to leave gaps. The chain of Rake tasks ends at a login that only works for the account which registered the application, the two registration walkthroughs disagree about the form, and `make` is an entire entry point the build instructions never acknowledge. Anyone picking this up should read the Rakefile before trusting the README's four commands, keep a personal WordPress.com application for their own logins, and check .xcode-version and .ruby-version before touching Sources/ or Tests/.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. wordpress-mobile/WordPress-iOS on GitHub