oi-contest-schedule/AGENTS.md

Repository Instructions

Scope and source layout

• These instructions apply to the whole repository.
• Treat root PHP files, includes/, assets/, languages/, and readme.txt as source. Never edit build/ or release ZIP files directly; ./build.sh build recreates them.
• Read README.md for installation, shortcode, feed, cache, build, and layout details. Keep README_zh.md synchronized when changing shared documentation.
• The plugin supports WordPress 6.4+ and PHP 7.4+. Do not introduce syntax requiring a newer PHP version.
• Preserve the existing WordPress naming and security conventions: OICS_ classes/constants, oics_ hooks/handles/keys/functions, direct-access guards, safe remote requests, sanitization, and context-appropriate escaping.

Architecture

• vblg-oi-contest-schedule.php owns plugin metadata, constants, loading, and startup hooks.
• includes/class-plugin.php owns WordPress integration, widgets, shortcode registration, and asset enqueueing.
• includes/class-contest-client.php owns remote fetching, transient caching, validation, normalization, and sorting.
• includes/class-schedule-renderer.php owns escaped server-rendered markup.
• assets/js/schedule.js formats Unix timestamps in the visitor's locale/time zone and updates countdowns; assets/css/schedule.css owns presentation.
• Keep the transient key synchronized between the contest client and uninstall.php.

Localization and text changes

• Whenever modifying a file that contains text, explicitly check whether the change adds, removes, or changes user-facing/translatable strings and whether languages/vblg-oi-contest-schedule.pot and languages/vblg-oi-contest-schedule-zh_CN.po must also change.
• PHP gettext calls use the vblg-oi-contest-schedule text domain. Translations are loaded by WordPress automatically; the plugin does not call load_plugin_textdomain(), and the packaged ZIP does not include languages/. JavaScript-facing translated strings are localized from PHP.
• Treat POT and PO files as editable localization sources. MO files are generated by the build and must not be committed from the source tree.
• After PO changes, run ./build.sh build; it validates gettext syntax and format placeholders with msgfmt.

Validation

• Run ./build.sh build after code, metadata, readme, asset, or translation changes. This is the repository's packaging and automated validation command.
• Use ./build.sh clean only to remove generated build/ and ZIP artifacts.
• There is no separate test, lint, Composer, or npm command. Do not invent one; add focused manual checks when behavior cannot be covered by the build.

Release requests

When the user's message is exactly release X.Y.Z or release vX.Y.Z (allowing surrounding whitespace), perform the release preparation workflow below. Normalize the requested version to X.Y.Z and the tag to vX.Y.Z.

1. Confirm the version is valid SemVer and inspect the worktree before editing. Do not overwrite unrelated user changes.
2. Find the previous release tag from Git history, preferring the nearest reachable version tag: git describe --tags --abbrev=0 --match 'v*'. If none exists, state that the release notes cover the full repository history.
3. Search tracked source files for the current version and release metadata. Update every applicable version occurrence, including the plugin header and OICS_VERSION in vblg-oi-contest-schedule.php, Stable tag plus changelog/upgrade-notice headings in readme.txt, and Project-Id-Version in both PO and POT files. Review other search results rather than assuming this list is exhaustive. Do not edit generated copies under build/.
4. Review git diff <previous-tag>..HEAD and the commit log over the same range. Derive release notes only from that evidence; group user-visible changes, fixes, compatibility changes, and developer-facing changes as appropriate. Do not include uncommitted release-preparation edits as previously completed work unless clearly labeled.
5. Add concise release entries to the repository changelog/upgrade notice where appropriate, keeping WordPress.org formatting valid. Check whether English and Chinese documentation or translations need corresponding updates.
6. Run ./build.sh build and report any validation failures. Confirm the produced ZIP version and the requested tag agree with the plugin header and Stable tag.
7. Return release notes in both English and Simplified Chinese. The notes must be Markdown wrapped in a fenced code block, with clear English and 简体中文 sections. Include the version and comparison range (<previous-tag>...vX.Y.Z, or full history when no tag exists). Do not create a commit, tag, GitHub Release, or push unless the user explicitly requests it.

The release tag must equal v<plugin-header-version> because the packaging workflow enforces that relationship. WordPress.org version tags are immutable; never attempt to overwrite an existing release tag.