diff --git a/README.md b/README.md index 6d7a189..383616d 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,126 @@ -# ucsc-communications-functionality +# UCSC Communications Custom Functionality -Custom Functionality Plugin for UCSC's Communications website on the CampusPress network. +[![CI](https://github.com/ucsc/ucsc-communications-functionality/actions/workflows/ci.yml/badge.svg)](https://github.com/ucsc/ucsc-communications-functionality/actions/workflows/ci.yml) -This plugin currently provides two short codes: +Custom functionality plugin for the UC Santa Cruz Communications and Marketing website +on the CampusPress network. It provides the **A-Z Editorial Style Guide** — a custom +post type, its ACF field group, and two shortcodes for rendering entries — plus an +informational settings page in the admin. -- `[style-definition]`: Displays the style definitions for each Editorial Style Guide post type -- `[style-archive]`: Displays a loop of the style guide posts on the Editorial Style Guide page +## Requirements -This plugin also saves and loads ACF field groups to and from the plugin's `acf-json` folder. +| Requirement | Version | +| ------------------------------ | -------------------- | +| WordPress | 6.1 or later | +| PHP | 7.4 or later | +| **Advanced Custom Fields Pro** | Required — see below | + +ACF Pro is a hard dependency, not an enhancement. The `a_z_style_guide` post type is +registered **by ACF** from `acf-json/post_type_685d7e97c87c6.json`, not in PHP, so +without ACF Pro active the post type does not exist and both shortcodes render nothing. +The plugin declares this via `Requires Plugins: advanced-custom-fields-pro` in the +plugin header; it does not bundle or install ACF Pro for you. + +## Installation + +1. Download the latest `ucsc-communications-functionality.zip` from the + [releases page](https://github.com/ucsc/ucsc-communications-functionality/releases). +2. In WordPress, go to **Plugins → Add New → Upload Plugin** and upload the zip. +3. Activate the plugin. Make sure ACF Pro is active too. + +Once active, a read-only info page listing the version and available features lives at +**Settings → UCSC Communications Functionality** (requires the `manage_options` +capability). + +## Usage + +Style guide entries are managed under the **A-Z Ed Style Guide** menu in the admin. +Each entry has a **Style Definitions** repeater field, where every row holds: + +- **Editorial Style Item** — the term, plain text +- **Editorial Style Definition** — the guidance, a WYSIWYG field + +Two shortcodes render those rows: + +| Shortcode | Output | +| -------------------- | ----------------------------------------------------------------------------- | +| `[style-definition]` | The Style Definitions of the post it is placed on. | +| `[style-archive]` | Every published style guide entry, ordered by title ascending, with headings. | + +Neither shortcode takes attributes. Both are defined in +[lib/functions/shortcodes.php](lib/functions/shortcodes.php). + +## Development + +```bash +git clone https://github.com/ucsc/ucsc-communications-functionality.git +cd ucsc-communications-functionality +composer install +npm install +``` + +### Commands + +| Command | What it does | +| ----------------------- | ------------------------------------------------------------------- | +| `composer run lint` | PHP CodeSniffer — WordPress-Extra, WordPress-Docs, PHPCompatibility | +| `composer run lint-fix` | Auto-fix the PHPCS violations that are fixable | +| `composer run test` | PHPUnit | +| `composer run check` | `lint` then `test` — run this before opening a PR | +| `npm run dryrun` | Preview the next version bump without committing | +| `npm run release` | Bump the version and update the changelog | +| `npm run zip` | Package the plugin as a distributable zip | + +There is no build step — the plugin ships no compiled assets. + +### Tests + +The suite in [tests/](tests/) runs against hand-written WordPress and ACF doubles, so it +needs no WordPress install, no database, and no ACF Pro. It does need PHP's `mbstring` +extension. If your local PHP lacks it, either install it +(`sudo apt install php8.5-mbstring`) or run the suite in a container: + +```bash +docker run --rm -v "$PWD":/app -w /app --user "$(id -u):$(id -g)" \ + php:8.3-cli ./vendor/bin/phpunit +``` + +### Project layout + +``` +plugin.php Plugin header, constants, ACF JSON save/load filters +lib/functions/general.php Admin stylesheet enqueue +lib/functions/settings.php Settings → info page +lib/functions/shortcodes.php [style-definition] and [style-archive] +lib/css/ Admin settings page styles +acf-json/ Version-controlled ACF field group and CPT definitions +tests/ PHPUnit suite plus the WP/ACF doubles it runs against +``` + +Field group definitions are kept in `acf-json/` rather than the database: `plugin.php` +filters `acf/settings/save_json` and `acf/settings/load_json` so ACF reads and writes +them there, keeping them under version control. + +## Releasing + +`npm run release` uses [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) +to bump `package.json`, `package-lock.json`, and the `Version:` header in `plugin.php` +(through `wp-plugin-version-updater.js`), and to update `CHANGELOG.md` from the commit +history. Push the resulting `v*.*.*` tag and +[.github/workflows/release.yml](.github/workflows/release.yml) builds the zip and +publishes the GitHub release via the shared `ucsc/actions` workflow. + +## Contributing + +[.github/workflows/ci.yml](.github/workflows/ci.yml) runs PHPCS on PHP 8.3 and PHPUnit +on PHP 8.3 and 8.4 for every pull request, so `composer run check` should pass locally +first. Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) — +the changelog is generated from them. + +For architecture notes, known quirks, and the gotchas worth reading before changing +anything, see [CLAUDE.md](CLAUDE.md). [ROADMAP.md](ROADMAP.md) records the original +audit items with their causes and fixes. + +## License + +GPL-3.0-or-later. See [LICENSE](LICENSE).