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.