# Monolytics for WordPress

Official Monolytics plugin repository for WordPress.

Current status:

- initial PHP runtime scaffold is in place
- local packaging script, CI artifact build, and manual GitHub-token release flow are in place
- WordPress.org-ready listing metadata and release workflows are in place
- plugin approval and SVN access are in place
- the repository now includes the first public WordPress.org listing asset pack
- first public WordPress.org publish still requires merge to `main`, the next release tag, and a manual publish run for that tag

Canonical repo docs:

- `AGENTS.md`
- `CLAUDE.md`
- `docs/ai-spec/core.md`
- `docs/ai-spec/features/wordpress-plugin.md`
- `docs/ai-spec/playbooks/release-versioning.md`
- `docs/ai-spec/playbooks/wordpress-org-submission-pack.md`

Repository scope:

- WordPress plugin implementation
- packaging and release automation
- WordPress-facing product/docs for the plugin

Out of scope:

- Monolytics Cloud/backend implementation
- canonical backend/API ownership for plugin-required endpoints

Cross-repo note:

- Cloud/backend contracts for this plugin still live in `monolytics/monolytics`
- if plugin work requires backend/API changes, deliver those changes in the Monolytics monorepo and keep the linked Linear issue/PR chain synchronized

## Development

Common local commands:

- `brew install php composer` on macOS if the local machine does not already provide them
- `composer install`
- `composer test`
- `composer release:verify`
- `composer package:smoke`
- `composer package`

Packaging output:

- local package script writes the installable zip to `build/monolytics-<version>.zip`
- package smoke test validates the zip from a clean temporary checkout and asserts the `monolytics/` root folder plus `monolytics.php` bootstrap

## Release Model

This repository now follows a WordPress.org-first release path:

- version bumps and changelog edits flow through a dedicated manual `chore(release): …` PR that updates `monolytics.php`, `readme.txt`, and `CHANGELOG.md` together
- merging that PR to `main` is followed by a local `gh release create --target main --generate-notes` call using the operator's personal `gh auth token`, which creates the canonical tag and GitHub Release
- `Release Plugin Package` runs from `release.published` and attaches the installable plugin zip to that GitHub Release
- `pull_request`, `push` to `main`, and `workflow_dispatch` run `Build Plugin Package` for validation and upload an installable GitHub Actions artifact whose downloaded zip can be uploaded directly to WordPress
- `Publish to WordPress.org` is a separate manual workflow with an approval boundary and WordPress.org SVN credentials
- WordPress.org publish does not auto-run when GitHub creates a release; an operator must trigger it intentionally for the exact release tag that should go live

Required release metadata:

- plugin version in `monolytics.php`
- matching `Stable tag` in `readme.txt`
- WordPress.org-compatible plugin headers and readme sections

Required GitHub secrets for WordPress.org publication:

- `WPORG_PLUGIN_SLUG`
- `WPORG_SVN_USERNAME`
- `WPORG_SVN_PASSWORD`

No release-specific PAT is required — `Release Plugin Package` and `Build Plugin Package` use the built-in `${{ github.token }}`, and GitHub Releases are created locally with the operator's personal `gh auth token`.

Optional WordPress.org listing assets can live in `.wordpress-org/assets/` and will be synced to the WordPress.org `assets/` directory by the publish workflow.

Use `.wordpress-org/assets/README.md` as the canonical filename and screenshot blueprint for those assets.

Operator command for publishing an already-created GitHub release tag to WordPress.org:

```bash
gh workflow run "Publish to WordPress.org" \
  -R monolytics/monolytics-wordpress-plugin \
  -f release_tag=monolytics-wordpress-plugin-vX.Y.Z
```

If listing assets or `readme.txt` changed after the last GitHub release, merge those changes first and publish the next release tag instead of reusing the older one.

Owner-side prerequisites that still sit outside repository automation:

- final publisher account and support-contact confirmation
- intentional operator decision about which release tag should become the first public WordPress.org directory version