# WP Plugin Auto-Release (Gitea Actions)

Automatically versions and releases this WordPress plugin whenever the
plugin's `Version:` header changes on `main`. No manual tagging, no
hardcoded plugin name/slug — everything is read straight from the plugin's
own file header.

## What it does

On every push to `main`, the workflow at
[`.gitea/workflows/wp-plugin-release.yml`](.gitea/workflows/wp-plugin-release.yml) runs:

1. **Locate the main plugin file** — scans all `*.php` files for one
   containing a `Plugin Name:` header (skips `vendor/`, `node_modules/`,
   `build/`).
2. **Extract metadata** — reads `Plugin Name:` and `Version:` from that
   file's header comment, then derives a slug from the plugin name
   (e.g. `My Cool Plugin` → `my-cool-plugin`).
3. **Check for a new version** — looks for a git tag `vX.Y.Z` matching the
   version found in step 2.
   - **Tag already exists** → workflow stops here. Pushing commits without
     bumping the version does nothing.
   - **Tag doesn't exist** → it's a new release, continue.
4. **Sync `readme.txt`** — updates the `Stable tag:` line to match, if the
   file exists, and commits that change back to `main`.
5. **Tag** the commit as `vX.Y.Z` and push the tag.
6. **Build a zip** of the plugin (excluding `.git`, `.gitea`, `.github`,
   `node_modules`, `build`), named `<slug>-<version>.zip`.
7. **Publish a Gitea Release** for the new tag with the zip attached as a
   downloadable asset.

## Requirements

- A **Gitea Actions runner** (`act_runner`) registered on your instance.
- The runner image needs `rsync`, `zip`, and `git` available (standard on
  `ubuntu-latest`-style runner images).
- A **repo secret** named `RELEASE_TOKEN` — a Gitea access token with
  repo write / release permissions. Add it under
  **Repo → Settings → Secrets**.

## Usage

1. Bump the version in your plugin's main file header:

   ```php
   /**
    * Plugin Name: My Cool Plugin
    * Version: 1.3.0
    */
   ```

2. Commit and push to `main`:

   ```bash
   git add .
   git commit -m "Release 1.3.0"
   git push origin main
   ```

3. The workflow detects the new version, tags `v1.3.0`, builds
   `my-cool-plugin-1.3.0.zip`, and publishes it as a Gitea release —
   nothing else to do.

## Plugin file requirements

Your main plugin file must use the standard WordPress header format,
with `Plugin Name:` and `Version:` inside the top `/** ... */` comment
block:

```php
<?php
/**
 * Plugin Name: My Cool Plugin
 * Description: Does cool things.
 * Version: 1.3.0
 * Author: You
 */
```

If your header format differs significantly (e.g. Version defined only
as a PHP constant with no header line), the parsing step in the workflow
will need a small adjustment.

## Notes & caveats

- **One release per version.** If you push multiple commits without
  changing `Version:`, no new tag/release is created — this avoids
  duplicate releases on every push.
- **`readme.txt` sync** only runs if the file exists at the repo root;
  it's skipped otherwise.
- **Tags are immutable once created** by this workflow — to "redo" a
  release, delete the tag and Gitea release first, then push again.
- The zip excludes `.git`, `.gitea`, `.github`, `node_modules`, and
  `build` — add more `--exclude` patterns in the "Build plugin zip" step
  if you have other dev-only directories (e.g. `tests/`, `.vscode/`).