Rewrite README.md as a developer/contributor landing page

README.md

@@ -1,20 +1,109 @@
-# super-cache
+# WP Super Cache
 
-A very fast caching engine for WordPress that produces static html files.
+A very fast caching engine for WordPress that produces static HTML files.
 
-## How to install super-cache
+[![WordPress Plugin](https://img.shields.io/wordpress/plugin/v/wp-super-cache)](https://wordpress.org/plugins/wp-super-cache/)
+[![License: GPLv2+](https://img.shields.io/badge/License-GPLv2%2B-blue.svg)](./LICENSE.txt)
+[![PHP 7.4+](https://img.shields.io/badge/PHP-7.4%2B-7A86B8.svg)](https://www.php.net/)
+[![PHP Tests](https://github.com/Automattic/wp-super-cache/actions/workflows/php-tests.yml/badge.svg)](https://github.com/Automattic/wp-super-cache/actions/workflows/php-tests.yml)
 
-### Installation From Git Repo
+This plugin generates static HTML files from your dynamic WordPress site. After a file is generated, the web server serves that file directly instead of processing WordPress PHP scripts, dramatically reducing load and response times.
 
-## Contribute
+For user-facing documentation, see the [WordPress.org plugin page](https://wordpress.org/plugins/wp-super-cache/). For extended documentation, see the [wiki](https://github.com/Automattic/wp-super-cache/wiki).
+
+## Project structure
+
+```
+wp-cache.php              Main plugin entry point
+wp-cache-phase1.php       Early-loading caching phase (runs before WordPress)
+wp-cache-phase2.php       Main caching logic (runs during WordPress init)
+advanced-cache.php        Drop-in loaded by WordPress when WP_CACHE is enabled
+ossdl-cdn.php             CDN URL rewriting (OSSDL off-linker integration)
+
+inc/                      Core includes (Boost integration, admin UI helpers)
+rest/                     REST API endpoint classes for cache management
+src/                      Source modules (device detection)
+plugins/                  WP Super Cache's own plugin system (loaded early, before WP)
+partials/                 Admin settings page tab templates
+
+tests/php/                PHPUnit tests
+tests/e2e/                End-to-end tests (Docker + Jest)
+
+changelog/                Individual changelog entries (Jetpack Changelogger format)
+.phan/                    Phan static analysis configuration and stubs
+```
+
+## Development setup
+
+### Prerequisites
+
+- PHP 7.4+
+- [Composer](https://getcomposer.org/)
+
+### Installation
+
+```bash
+composer install
+```
+
+### Running tests
+
+```bash
+# PHP unit tests
+composer test-php
+
+# With coverage
+composer test-coverage
+```
+
+### Linting
+
+```bash
+# PHPCS (WordPress/Jetpack coding standards)
+vendor/bin/phpcs
+```
+
+### Static analysis
+
+```bash
+# Phan
+vendor/bin/phan
+```
+
+### End-to-end tests
+
+E2E tests use Docker and Jest. See `tests/e2e/` for setup details:
+
+```bash
+cd tests/e2e
+pnpm install
+docker compose up -d
+pnpm test
+```
+
+## Contributing
+
+1. Branch from `trunk`.
+2. Make your changes.
+3. Add a changelog entry:
+   ```bash
+   vendor/bin/changelogger add
+   ```
+4. Push and open a pull request against `trunk`.
+
+CI will automatically run:
+- **PHP tests** across PHP 8.2, 8.3, 8.4, and 8.5
+- **PHPCS linting** on changed lines
+- **Changelog validation** (warns if no entry is included)
+
+### Translations
+
+Help translate WP Super Cache on the [WordPress.org translation page](https://translate.wordpress.org/projects/wp-plugins/wp-super-cache).
 
-## Get Help
-Support is handled via the .org support forums.
 ## Security
 
-Need to report a security vulnerability? Go to [https://automattic.com/security/](https://automattic.com/security/) or directly to our security bug bounty site [https://hackerone.com/automattic](https://hackerone.com/automattic).
+To report a security vulnerability, visit [automattic.com/security](https://automattic.com/security/) or the [HackerOne bug bounty program](https://hackerone.com/automattic).
 
 ## License
 
-super-cache is licensed under [GNU General Public License v2 (or later)](./LICENSE.txt)
-
+WP Super Cache is licensed under the [GNU General Public License v2 (or later)](./LICENSE.txt).