docs: reinstate WordPress.com OAuth2 setup for contributors

[dcalhoun]

Description

WordPress.com OAuth2 documentation was removed in #20928 because passkey-related API changes had broken the authentication flow for anyone building without our secrets. Now that login is rebuilt on a web-based authorization flow, external contributors can register their own WordPress.com application and sign in again, so this reinstates the documentation — and adds the Git-ignored configuration file it needs.

Three commits:

1. build: settings.gradle now layers a Git-ignored secrets.properties at the root of the repository over whichever base applies, so values there take precedence over defaults.properties and over any secrets applied by configure_apply. Keys the file leaves out keep their existing value, so it only needs the entries being overridden. Previously the only place to change wp.oauth.app_id was defaults.properties, a tracked file — an easy way for a contributor to commit their client secret by accident. secrets.properties-example is the copy target and .gitignore covers the copy.

2. docs: docs/wpcom-authentication.md documents the setup, with pointers from the README and the docs index. The step the old instructions did not cover is registering both wordpress://wpcom-authorize and jetpack://wpcom-authorize as Redirect URLs: the flow now returns to the app through a URL scheme that differs per app, and WordPress.com only redirects to an exact match. This also drops the README's "Access to WordPress.com features is temporarily disabled in the development environment" note, which is no longer true.

3. docs: removes five link reference definitions in the README that nothing points at. [5], [6] and [7] belonged to the OAuth2 section Replaces OAuth2 section with self-hosted test instructions #20928 removed; the body links to Android Studio and the WordPress Slack inline rather than through [3] and [4]. Link reference definitions render as nothing, so the page is unchanged.

The Gradle change is the part worth the closest look, since it alters secret precedence for everyone rather than only for contributors.

Internal context: p1784211249505409-slack-C04PWEZSYFL

Testing instructions

Verify the override reaches BuildConfig (no WordPress.com application needed):

1. Create secrets.properties in the root of the repository containing wp.oauth.app_id = test_client_id_12345.
2. Run ./gradlew :WordPress:generateJetpackDebugBuildConfig.

• Verify the configuration log includes Applying local secret overrides from secrets.properties.
• Verify OAUTH_APP_ID in WordPress/build/generated/source/buildConfig/jetpack/debug/org/wordpress/android/BuildConfig.java is test_client_id_12345, even with our secrets applied.

3. Delete secrets.properties and run the task again.

• Verify OAUTH_APP_ID is back to its usual value, and that git status never listed secrets.properties.

Verify the documented setup end to end, ideally with our secrets disabled so you are on the contributor path:

1. Follow docs/wpcom-authentication.md with a WordPress.com application of your own, registering both redirect URLs.
2. Build and install jetpackDebug, then choose "Log in or sign up with WordPress.com".

• Verify authentication completes in the browser and returns to the app signed in.

3. Repeat with wordpressDebug.

• Verify the same, confirming both redirect URLs are needed.

Read the rendered README and docs index.

• Verify the WordPress.com Authentication links resolve and the page is otherwise unchanged by the reference-definition cleanup.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HSP5MJmVBoiqtwBhaa4eHo

[wpmobilebot]

📲 You can test the changes from this Pull Request in Jetpack Android by scanning the QR code below to install the corresponding build.

	App Name	Jetpack Android
	Build Type	Debug
	Version	pr23288-e13d679
	Build Number	1498
	Application ID	com.jetpack.android.prealpha
	Commit	e13d679
	Installation URL	69t3tlarkm40o

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

[wpmobilebot]

📲 You can test the changes from this Pull Request in WordPress Android by scanning the QR code below to install the corresponding build.

	App Name	WordPress Android
	Build Type	Debug
	Version	pr23288-e13d679
	Build Number	1498
	Application ID	org.wordpress.android.prealpha
	Commit	e13d679
	Installation URL	40m80qoipl2g0

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

[ParaskP7]

👋 @dcalhoun !

I have reviewed and tested this PR as per the instructions, everything works as expected, good job and thank YOU! 🌟 x 🌟 ^ 🌟

I verified the override reaches BuildConfig with our secrets applied, so a local secrets.properties does take precedence over ~/.configure/wordpress-android/secrets/secrets.properties. The documented setup also matches what we worked through in the thread back in July, both redirect URLs and both apps. And the README reference-definition cleanup is safe, [1] and [8] are the only ones left and both are still pointed at.

---

I have left a question (❓) below for you to consider. I am going to approve this PR anyway, since it is not blocking. I am NOT going to merge this PR yet to give you some time to reply. However, feel free to ignore it and merge the PR yourself.

---

Question (❓): Mostly so that we have it stated explicitly and in writing, is the precedence deliberate? That is, a local secrets.properties overriding the secrets applied by configure_apply, rather than only filling in when those are absent. I am fairly confident it is, since testing step 2 asks to verify the override "even with our secrets applied", and it is what lets one of us try our own OAuth2 application without relocating ~/.configure/wordpress-android the way you did in July. So this is a confirmation request, not a change request.

FYI: Alternative

For reference, the alternative would be to make the local file a fallback-only overlay, so applied secrets can never be shadowed, though it would cost you exactly that "even with our secrets applied" path:

static def loadSecrets(Logger logger, File defaultsFile, File secretsFile, File localSecretsFile) {
    if (secretsFile.exists()) {
        return loadPropertiesFromFile(secretsFile)
    }

    logger.warn("Secrets file not found. Using defaults.")
    def properties = loadPropertiesFromFile(defaultsFile)
    if (localSecretsFile.exists()) {
        logger.lifecycle("Applying local secret overrides from ${localSecretsFile.name}.")
        properties.putAll(loadPropertiesFromFile(localSecretsFile))
    }
    return properties
}