A bugfix changes ONLY the lines that fix the bug. No restructuring, no renaming, no restyling on the way past, no "refactor" commit inside a bugfix PR.
Read the function's history first: git log --oneline -L <start>,<end>:<file>. The hot code gets edited over and over, and the fixes it holds are not visible in the code itself. The drag-and-drop block in assets/public/js/script.js carries 17 commits, Controller\Common\API::register_endpoints() 14, openModal() in script.js 13, Shortcode::callback_roadmap() 11, Model\Roadmap::get_roadmap() 10 (plus 5 more before it was extracted, see below), API\Task::get() 8. Examples of fixes you can't see:
- The per-item permission checks
Auth::can_move_task(),can_order_tasks()andcan_order_stages()came ineb1e081misc (no PR, no issue, no body). Before that, the routes only checkededit_pages, with no check on the item or status itself. - The guards in
Common\Init::order_terms()(only fullWP_Termobjects are sorted, unsorted statuses go last) came in2e8dc16reinit. board.phpputsdata-nr-per-columnafterhiddenso the markup the tests match keeps its shape, andNiroRoadmapPaging.reveal()keeps a dropped card visible (94ea24f, PR #57).Getting_Started::show_help_notice()marks the checklist done for sites that were already set up (eb050b5, no PR).
Treat existing code as accumulated fixes, not as arbitrary shape; the code IS the spec. Skipping this step is how a rewrite silently reverts an earlier fix and ships a new bug inside a bugfix.
A list of hashes is not the history. For EVERY commit -L returns, read three things: the commit, its PR, and its issue. The one-line subject is a label, not a reason. The reason lives in the commit body, the PR description and the issue that prompted it, and that is where the constraint you are about to break is written down.
If a 10-line function was built by 6 commits, that is 6 commit messages + 6 PR bodies + 6 issues to read before you touch it: all six, not the newest one, not "the relevant-looking ones". A rule you did not read is a rule you will delete.
git log --oneline -L '/public static function get_roadmap/,+163:app/Model/Roadmap.php' # the hashes
git show <sha> # full body + diff, per hash
gh api repos/codexpertio/niroroadmap/commits/<sha>/pulls --jq '.[].number' # commit → PR
gh pr view <n> --json title,body,comments # why it was written that way
gh issue view <nn> # the report + repro it had to satisfyWhere the PR and issue are in this repo:
- PRs #46–#54 (the 1.0 features) were rebase-merged. There is no merge commit, and the
Closes #NNis in the PR body, not the commit body. Use the API to go from commit to PR. A rebase can change the SHA: PR #51's19ba64cis54cf40con master, so the API is the reliable route. - PR #57 and later are merge commits (
Merge pull request #NN from …) and the fix commit carriesCloses #NNin its body. Take the number from there; fall back to the API only when it is missing. - PR #47 (
bed152e, issue #18) was merged intofeature/19-settings-page, not master. Its commit still reached master, and the API still maps it to #47. - Before
0fc93earename (2026-09-10) the plugin was EasyRoadmap. The only PRs then were #1, #2, #11, #12, #16 and #17 (merge commits).
If a commit has no PR and no issue, say so in your list. That is a real finding: the constraint is undocumented and the commit body is all there is. Here that is 67 of the 73 commits before the rename, with no body either (misc, cs, reinit, re-re-init, More fixes), so the diff read line by line is the only record. After 1.0 it is every commit outside PRs #54 and #57, including 1a2cda5 (onboarding) and eb050b5 (a fix inside a changelog commit).
If the function was moved or extracted, follow it. git log -L follows a file rename but does NOT track content across files, so it reports almost no history on exactly the code that has the most.
-
Roadmap::get_roadmap()began insideShortcode::callback_roadmap(), moved toController/Common/Roadmap.phpinb1e66a8, then toModel/Roadmap.phpin3d53269.-Lfollows the rename back tob1e66a8and stops; the 5 commits before it are inShortcode.php:git log --oneline -L '/public function callback_roadmap/,+45:app/Controller/Public/Shortcode.php' b1e66a8^ -
c5eb080splitviews/shortcodes/roadmap.phpintoboard.php,list.phpandtimeline.php.-Lonboard.phpshows 3 commits; the board markup's earlier history is inroadmap.php:git log --oneline -L '/nr-kanban-columns/,+60:views/shortcodes/roadmap.php' c5eb080^ -
PHP 7.4 support renamed
app/Trait/→app/Traits/andapp/Controller/Public/→app/Controller/Front/(namespaces with them).-Lfollows those renames;git log -- <old path>does not.
git log --oneline --diff-filter=ADR -M -- <file> lists where a file was added, deleted or renamed.
List them in the PR body: which prior fixes touch these lines, and which the diff preserves. If the diff moves one, say why. No list means nobody looked.
Size gate: more than ~20 changed lines inside an existing function in a bugfix → stop, justify, or split. A big bugfix diff is churn until proven otherwise. Reference points: eb050b5 fixed the setup reminder for sites already set up with +6 lines in show_help_notice(); the review fixes for PR #57 (94ea24f) changed one line of board.php and added a separate reveal() rather than rewriting refresh().
Never extract a shared helper as part of a bugfix. Several rules are hand-written in more than one place, and the copies have already drifted apart:
- "Which items are public" is checked in three places:
Roadmap::get_public_item()(REST),Submission::similar()(has_password => false) and the board query inget_roadmap(). The board query is missing the password check (#62). - "Every item, whatever its status" is written as
post_status => array( 'any', 'trash', 'auto-draft' )inuninstall.phpand twice inSample_Data('any'alone skips trash and auto-draft). - What a setting hides (vote counts, tags, target) is enforced separately in
Toolbar::config(),Views::config(),Task::can_see_count(),Fields::public_facts()and each template.
Say so when you notice it, but consolidation is its own scheduled PR with behaviour locked by tests first, never a side effect of fixing one instance.
Public product roadmap for WordPress by NiroSuite (Codexpert). Items are a custom post type shown as a Kanban
board, a list or a timeline through the [niroroadmap] shortcode or the niroroadmap/roadmap block. Visitors
vote, comment and suggest ideas; editors drag cards on the public board. Published on WordPress.org as niroroadmap.
| Item | Value |
|---|---|
| Version | 1.3.0 — plugin header Version, NIROROADMAP_VERSION and readme.txt Stable tag must agree (the release workflow checks header and Stable tag against the tag; nothing checks the constant) |
| PHP namespace | NiroRoadmap\ → app/ (PSR-4, Proper_Case files: app/Model/Status_Log.php = NiroRoadmap\Model\Status_Log) |
| Autoload files | app/Helper/functions.php, app/Config/autoload.php (Composer files) |
| Requires | PHP 7.4 (runs on 7.4 through 8.5), WP 6.0, tested up to 7.1 |
| Text domain | niroroadmap (no load_plugin_textdomain() call) |
| REST namespace | niroroadmap/v1 (Traits\Rest::$namespace) |
| Prefixes | niroroadmap_ options/hooks/meta, NIROROADMAP_ constants, niroroadmap- script handles, nr- CSS classes and DOM ids, data-nr-* JS hooks |
| Runtime deps | none (Composer is autoload only) |
| License | GPLv2 or later |
vendor/ and build/ are gitignored. A fresh checkout fatals on require_once 'vendor/autoload.php' until composer install; without build/ the block is simply not registered (Common\Blocks checks for build/blocks-manifest.php).
composer install # PHP deps (dev: phpunit 9.6, brain/monkey, phpcs + WPCS + PHPCompatibility); platform pinned to PHP 7.4
composer test # php -d auto_prepend_file=tests/bootstrap.php vendor/bin/phpunit (see Tests)
composer makepot # wp i18n make-pot → languages/niroroadmap.pot (needs WP-CLI)
composer release # build blocks, makepot, --no-dev install, zip → release/niroroadmap.zip
npm install
npm run start:blocks # wp-scripts watch: app/Blocks → build/
npm run build:blocks # wp-scripts build --blocks-manifest → build/ (only the block is compiled)Only app/Blocks/roadmap/ is compiled. Everything in assets/ is plain JS/CSS served as-is — edit and reload,
no build. There is no phpcs.xml and no lint script, although WPCS is a dev dependency.
niroroadmap.php Header, constants, activation/deactivation/plugins_loaded wiring, requires vendor/autoload.php
uninstall.php Option cleanup; full data removal only with the delete_on_uninstall setting
app/
Bootstrap/ Installer (activation), Activator (every load), Migrator (one-time data migrations), Initializer (controllers), Uninstaller (deactivation!)
Activator/ Post_Type, Taxonomy (registered on init)
Controller/
Admin/ Asset, Getting_Started, Init (status color field), Item_Fields, Settings, Submissions
Common/ API (REST routes), Blocks, Comments (auto-close), Fields (register meta), Init (assets, term order, vote cleanup), Status_History
Front/ Front (assets, body class, JS strings), Shortcode, Legacy_Urls (301 from the old archive slugs, rewrites old links in text)
API/ REST handlers: Task, Comment, Submission, Stage, Option
Model/ Roadmap (board data + render), Vote, Comment, Submission, Fields, Status_Log, Toolbar, Views
Helper/ Settings (schema), Voter, Rate_Limit, Sample_Data, Utility, functions.php
Traits/ Hook, Asset, Rest, Auth, Menu, Cleaner, Cache, Limiter
Blocks/roadmap/ block.json, index.js, edit.js, render.php, editor.scss (source of build/roadmap/)
Config/autoload.php Requires every other app/Config/*.php (there are none)
views/shortcodes/ roadmap.php (wrapper + popup), board.php, list.php, timeline.php, toolbar.php, switcher.php, suggest.php
assets/
common/ init.js, init.css, img/loader.gif — loaded on every front and admin page
public/js/ script.js (popup, votes, comments, suggest, drag, Load more), toolbar.js, views.js
public/css/ style.css, toolbar.css, views.css
admin/ css/style.css + js/sorter.js (status screen), css/getting-started.css; js/init.js, js/settings.js, css/settings.css are not loaded
tests/ bootstrap.php + PHP/*Test.php (integration, real WP database)
languages/ niroroadmap.pot (stale header, regenerated by composer release), cx-plugin.pot (scaffold leftover)
svn-assets/ WordPress.org banners, icons, screenshots, blueprints/blueprint.json (Playground demo)
.github/workflows/ wp-svn-release.yml (tag → WordPress.org SVN)
- Activation →
Installer::install()(see Lifecycle). plugins_loaded→Activator::activate(): CPT and taxonomies oninit,Installer::seed_statuses()oninit20,Installer::maybe_upgrade()(creates the two tables when their schema option differs),update_option( 'niroroadmap_activated', true ).plugins_loaded→Initializer::initialize()instantiates every class inController/Admin/whenis_admin(),Controller/Front/otherwise, andController/Common/always, by globbing the folder. A new controller file is loaded automatically; its constructor registers hooks throughTraits\Hook(action(),filter(),shortcode()).
Admin controllers are constructed before Common ones, so on the same hook and priority their callbacks run first.
| Name | Kind | Notes |
|---|---|---|
niroroadmap_item |
post type | Labels "Items", menu "NiroRoadmap", capability_type page, rewrite tasks, archive on, show_in_rest, supports title, editor, author, comments, thumbnail (thumbnail = popup cover) |
niroroadmap_status |
taxonomy (hierarchical) | Board columns. Rewrite slug roadmap-status. Term meta color, menu_order |
niroroadmap_product |
taxonomy (hierarchical) | Rewrite roadmap-product |
niroroadmap_tag |
taxonomy (flat) | Rewrite roadmap-tag |
{prefix}niroroadmap_votes |
table | One row per voter per item; UNIQUE (item_id, voter_hash) and (item_id, fingerprint_hash); schema option niroroadmap_schema_version |
{prefix}niroroadmap_status_log |
table | from/to term id + name snapshot, user_id, created_at UTC; schema option niroroadmap_status_log_schema |
upvote, downvote |
post meta (unprefixed) | Display counters, changed only by Vote::bump() in one SQL statement; existing pre-table counts are kept |
_niroroadmap_target, _target_sort, _release_date, _version, _effort, _notes, _link, _hide_votes, _pinned |
post meta | Model\Fields constants; registered with show_in_rest => false on purpose |
_niroroadmap_submitted, _submitter_name, _submitter_email |
post meta | Visitor submissions (Model\Submission constants) |
_niroroadmap_sample |
post + term meta | Example content flag (Sample_Data::FLAG) |
niroroadmap_settings |
option | All settings (see Settings) |
niroroadmap_db_version, niroroadmap_activated, niroroadmap_page_id (legacy roadmap page), niroroadmap_statuses_seeded (pending/yes), niroroadmap_getting_started_done, niroroadmap_migration_version (Migrator::VERSION; set on a fresh install so it never scans), niroroadmap_links_cursor (last post ID the background link migration handled; gone when done), niroroadmap_rewrite_version (Activator::REWRITE_VERSION) |
options | |
niroroadmap_activation_redirect (60 s), niroroadmap_field_errors_{user_id} (5 min), niroroadmap_rl_{md5} |
transients | Redirect to Getting Started; meta box errors; rate limit windows |
niroroadmap_voter |
cookie | Anonymous voter token, 32 hex chars, 1 year, HttpOnly, SameSite=Lax |
niroroadmap_votes, niroroadmap_view |
localStorage | UI cache of own votes; last chosen view |
Default statuses seeded once on a fresh site: Under Review #a855f7, Planned #3b82f6, In Progress #f59e0b, Completed #22c55e (slugs under-review, planned, in-progress, completed). Deleted defaults never come back. submissions_status defaults to the under-review term; comment auto-close matches slug completed; the tests look these slugs up.
Status order: term meta menu_order, applied by the get_terms filter in Common\Init::order_terms() to every full-object query on niroroadmap_status (unsorted terms last, by id). Item order: menu_order of the post, pinned items first (stable sort).
Helper\Settings::fields() is the single schema: tab, type (checkbox|select|color|number|textarea|email), label,
description, default (value or Closure), options (Closure), cast int, min/max. It drives defaults,
Settings::get() casting, Settings::sanitize() and the form in Controller\Admin\Settings.
| Tab | Keys (default) |
|---|---|
| general | roadmap_page (legacy option), default_product (0), stage_links (off), show_vote_counts (on), show_tags (on), show_target (off), show_history (off), show_downvote (on) |
| voting | vote_who (everyone/logged_in), allow_vote_change (off), show_downvotes_to (everyone/admins) |
| comments | comments_enabled (off), comments_login (off), comments_order (oldest/newest), comments_auto_close (off) |
| submissions | submissions_enabled (off), submissions_login (off), submissions_identity (off/optional/required, optional), submissions_status (under-review term), submissions_auto_vote (on), submissions_notify (on), submissions_email ('') |
| toolbar | toolbar_enabled (off), toolbar_sort (manual), toolbar_filter_search, toolbar_filter_tag, toolbar_filter_product (on) |
| views | view_default (board), view_switcher (off), view_mobile_list (off), view_timeline_group (quarter), board_per_column (10, 0–500) |
| appearance | color_scheme (light/dark/auto), accent_color (#2563eb), card_radius (12, 0–32), custom_css ('') |
| advanced | delete_on_uninstall (off) |
- Read with
niroroadmap_get_setting( $key ); theniroroadmap_setting_{$key}filter has the last word (tests pin settings this way). - The form posts a hidden
_tab; unchecked checkboxes of that tab become false, everything else absent keeps its value. An invalid value is rejected with a settings error and keeps the saved value.sanitize()must give the same answer on its own output: WordPress runs it twice on the first save. Settings::update( $key, $value )writes one key without validation — internal use only (installer, blueprint).Settings::inline_css()turns accent, radius and scheme into CSS variables on.nr-board,.nr-kanban-columns,.nr-modal-overlayand appendscustom_css.- Reset:
admin-post.php?action=niroroadmap_reset_settings(nonce +manage_options) deletes the option.
Adding a setting: schema entry in fields(); read it with niroroadmap_get_setting(); pin it in the setUp() of every test class whose output it changes; describe it in readme.txt (Settings, Shortcode, FAQ). A per-board override also needs the shortcode attribute in Shortcode::callback_roadmap(), the attribute in block.json, the control in edit.js, sanitizing in render.php, and resolution in Toolbar::config() / Views::config() / Submission::enabled().
[niroroadmap] / [roadmap] (shortcode_atts tag roadmap) and the block's render.php both call
Model\Roadmap::get_roadmap( $product, $args ). The block has no product attribute (TODO in render.php); it
always uses default_product.
| Attribute | Values | Resolved in |
|---|---|---|
product |
term id | get_roadmap() (null → default_product) |
toolbar, sort, filters |
yes/no; manual votes newest oldest commented; comma list of search tag product or none |
Toolbar::config() |
view, switcher, group, per_column (block: perColumn) |
board list timeline; yes/no; quarter month nownext; 0–500 |
Views::config() |
submissions |
yes/no |
Submission::enabled() |
Anything else falls back to the setting, then to a safe default. What a board may offer is decided on the server
so a setting can't be bypassed: no votes sort when counts are hidden, no commented sort without comments, no
tag filter when tags are hidden, no product filter on a one-product board, no timeline unless show_target.
get_roadmap() runs one WP_Query per status (published items, menu_order), reads targets only when a list or
timeline is rendered, products/dates only when there is a toolbar, then renders views/shortcodes/roadmap.php
through Utility::get_template() (extracts $args keys and also leaves $args in scope; templates read
$args['key'] ?? default). Only views in $views['render'] are put in the page; without a switcher that is the
default view, plus the list when view_mobile_list applies. Every item appears once per rendered view with the
same data-task; only the board card carries id="nr-task-{id}".
The popup (#nr-modal-overlay) is printed once per request (did_action( 'niroroadmap_modal_rendered' )), the
suggest dialog once (niroroadmap_suggest_rendered). Tests unset these from $GLOBALS['wp_actions'] to render again.
Board columns print every card; cards past per_column get data-nr-over (CSS hides them) and the column a
Load more button. The header count is always the column total.
Assets: Front enqueues public/css/style.css (+ inline settings CSS), jQuery, jQuery UI Sortable and
public/js/script.js on every front-end page. Toolbar::enqueue() and Views::enqueue() register and
enqueue toolbar.* / views.* while a board renders, only when that board needs them. Common\Init loads
common/js/init.js + init.css and prints the #niroroadmap-modal loader on every front and admin page.
The PHP templates and the JS share a DOM contract (#nr-modal-*, .nr-kanban-item, .nr-view-item,
data-task, data-stage*, data-tags, data-tag-slugs, data-product-ids, data-date, data-target-sort,
data-pinned, data-nr-*). Change both sides together; ToolbarTest and ViewsTest match the markup with regexes,
so attribute order matters.
- Globals:
NIROROADMAP(api_base,nonce;settingswith strings and flags added byFrontthrough theniroroadmap-localized_varsfilter, front end only),NIROROADMAP_TOOLBAR.i18n,window.NiroRoadmapPaging(refresh( column ),reveal( card )). script.js: popup with zoom animation,GET /tasks/{id}, votes, comments (paged, one reply level), suggest dialog with focus trap and similar-item search, editor drag and drop, Load more. Only logged-in visitors (body classlogged-in) sendX-WP-Nonce. Guests send none, because core refuses an expired nonce with 403 even on public routes, and a cached page's nonce expires.- Drag and drop:
.task-editor .nr-kanban-listsortable; body classtask-editoris added foredit_pagesusers. On drop it posts/tasks/{id}/moveand/tasks/order(idsnr-task-{id}of that column).toolbar.jsdisables sorting while a search, filter or non-manual sort is active. toolbar.js: client-side only. Accent-folded search over title + tags with<mark>highlighting, sort within each column (pinned first), tag/product filters. State in the URL:nr_q,nr_sort,nr_tag,nr_product, suffixed_2,_3… for later toolbar boards on the page. Emitsnr:sortedon the board element.views.js: shows one[data-nr-view]panel;nr_view(+ suffix) in the URL,niroroadmap_viewin localStorage, list at ≤640 px whendata-nr-mobile-view; list column sorting viaaria-sortheaders.- Status screen:
admin/js/sorter.jsposts row idstag-{id}to/stages/order.
Routes live in Controller\Common\API::register_endpoints(); permission callbacks in Traits\Auth. Handlers answer
with Traits\Rest::response_success() / response_error() — status_header() + wp_send_json_*(), which exits.
They never return a WP_REST_Response; the body is { "success": bool, "data": … }. Tests therefore call
models, not handlers.
| Route | Who | Handler / notes |
|---|---|---|
GET /tasks/{id} |
public | Task::get: published, non-password items only (Roadmap::get_public_item); nocache_headers(); title, description, own voted, visible counts, Fields::public_facts(), history when show_history and >1 step |
POST /tasks/{id}/vote |
public | Task::vote: type upvote/downvote; 401 when vote_who = logged_in, 403 downvote off, 429 rate limit (30/10 min), 409 duplicate (with the recorded vote) |
GET /tasks/{id}/comments |
public | Comment::get: 404 when comments are off or the item isn't public; page, per_page 1–50 (20) |
POST /tasks/{id}/comments |
public | Comment::create: honeypot website, 5/10 min per IP except moderate_comments, then core wp_handle_comment_submission() |
POST /tasks/submit |
public | Submission::create: product optional (an empty value from "— Choose —" means none; a non-integer is 400), honeypot, login setting (401), elapsed ≥ min time (400), 3/hour except edit_others_posts, niroroadmap_submission_verify (403); a refused idea gives its rate-limit slot back. Response never contains the new id |
GET /tasks/search?q= |
public | Submission::search: 30/min, ≤5 published non-password items { id, title } |
POST /tasks/{id}/move |
can_move_task |
edit_post on the item + assign_term on the status → wp_set_post_terms() |
POST /tasks/order |
can_order_tasks |
every nr-task-{id} must be an item the user can edit → menu_order |
POST /stages/order |
can_order_stages |
every tag-{id} must be a status the user can edit → term meta menu_order |
GET, POST, DELETE /option |
manage_options |
Option: key must start with niroroadmap_; niroroadmap_settings is read-only here |
NIROROADMAP_SANDBOX (constant) makes every Auth check pass. Never define it outside a throwaway test site.
Helper\Voter::identify(): logged-in → HMAC of user id, no fingerprint; anonymous → HMAC of the cookie token plus a fingerprint (HMAC of IP + user agent). All hashes arehash_hmac( 'sha256', …, wp_salt( 'auth' ) ). Raw IP and UA are never stored. The cookie is issued on the first vote.Voter::ip_hash()keys rate limits: IPv6 by /64, IPv4-mapped IPv6 as IPv4. OnlyREMOTE_ADDRis trusted (niroroadmap_voter_ipfor proxies).Model\Vote::cast()inserts withINSERT IGNOREagainst the unique indexes, so the database decides who voted first; vote change is an atomic compare-and-set; counters move byGREATEST( meta + delta, 0 ). Unknown types throw (the type becomes a meta key).Helper\Rate_Limit: fixed window in a transient, serialised per subject with MySQLGET_LOCK; lock not acquired → denied.release()refunds a slot.- Hidden counts are left out of API responses (
Task::can_see_count()), not just hidden in CSS. Per item:_niroroadmap_hide_votes. Fields::public_facts()is the only public view of item meta: cover, target (only withshow_target), release, version, link. Effort and notes never leave the admin.- Comments are core comments;
Comment::format()returns plain text escaped then linked (a,p,bronly,nofollow ugc), never email or IP. Held comments are shown only to their logged-in author. - Submissions are created
pendingwith the submitter in protected meta; terms are set withwp_set_object_terms()because the visitor has no capabilities; the notification email builds the edit link by hand. Status_Historylogs everyset_object_termschange ofniroroadmap_statuson an item (editor, quick/bulk edit, REST move, imports), user 0 for code and visitors. The public timeline shows current status names and dates, never the user.
- Menu: CPT top level "NiroRoadmap" → Items, Add New, Statuses, Products, Tags, Getting Started (
edit_pages, slugniroroadmap-getting-started, menu entry removed onceniroroadmap_getting_started_doneis set), Settings (manage_options,edit.php?post_type=niroroadmap_item&page=niroroadmap-settings&tab=…). - Getting Started: four steps computed live from the site (example items don't count); redirect once after activation (not on bulk activation, AJAX, network admin); "New here?" notice on plugin screens until done; example content via
admin-post.php?action=niroroadmap_sample_items(do= add/remove,publish_pages), which also ensures statuses and the Roadmap page.Sample_Data::remove()deletes only flagged items and unused flagged terms. - Statuses screen: color field (add/edit, nonce-checked,
sanitize_hex_color), color column, drag to reorder. - Item screen (
Item_Fields): "Roadmap details" box (nonceniroroadmap_item_fields;Fields::sanitize()keeps the old value of an invalid field and queues a message in a transient, shown as a classic notice or a block editor notice — seetake_errors()for why theAcceptheader decides), "Status history" box (last 10). Items list: sortable Target and Votes columns (sort_list()keeps items without the meta and any existing meta query). - Submissions: "Submitted by" column; Approve row action on pending visitor submissions (
admin-post.php?action=niroroadmap_approve_submission, nonceniroroadmap_approve_{id},publish_post).
Filters: niroroadmap_setting_{$key}, niroroadmap-localized_vars (hyphen), niroroadmap_get_posts,
niroroadmap_show_stage_links, niroroadmap_vote_fingerprint, niroroadmap_voter_ip, niroroadmap_vote_rate_limit,
niroroadmap_comment_rate_limit, niroroadmap_comment_max_length (2000), niroroadmap_comment_show_avatars,
niroroadmap_completed_status_slugs, niroroadmap_submission_rate_limit, niroroadmap_submission_verify
(only a WP_Error rejects), niroroadmap_submissions_api_available, niroroadmap_submission_max_title (200),
niroroadmap_submission_max_description (2000), niroroadmap_submission_min_time (2000 ms),
niroroadmap_submission_notify_to, niroroadmap_docs_url, niroroadmap_support_url.
Actions: niroroadmap_comment_created, niroroadmap_submission_created, niroroadmap_archive_urls_changed (once, after the link migration, with old base => new base); internal once-per-page markers
niroroadmap_modal_rendered, niroroadmap_suggest_rendered.
- Integration tests against the WordPress install the plugin sits in (
tests/bootstrap.phploads../../../../wp-load.php, orWP_LOAD_PATH) and its real database. Never point them at production. Each test creates and deletes its own posts, terms and users. - WordPress must load before Composer's autoloader (
functions.phpexits withoutABSPATH), henceauto_prepend_filein thetestscript. - Classes in
tests/PHP/:CommentTest,FieldsTest,StatusHistoryTest,SubmissionTest,MigrationTest,RewriteTest,SampleDataTest,ToolbarTest,ViewsTest,VoteTest(154 tests, 626 assertions on PHP 7.4.30 and 8.3.0).SampleDataTestcallsitem_ids()andterm_in_use()only:remove()anduninstall.phpwould delete this site's real example content and data. - Run them on PHP 7.4 and the latest PHP:
php -d auto_prepend_file=tests/bootstrap.php vendor/bin/phpunitwith each binary. With Local, pass-d mysqli.default_socket=~/.config/Local/run/<site id>/mysql/mysqld.sock, and for 7.4 use Local's own PHP (lightning-services/php-7.4*/bin/linux/bin/phpwith itsshared-libsonLD_LIBRARY_PATHand-cthe site'sconf/php/php.ini). - Tests pin every setting they depend on with
niroroadmap_setting_{$key}filters, need the default status slugs to exist, and mark the block test incomplete whenbuild/is missing.
- No reserved word may be a namespace segment (
Trait,Public,Abstract,List,Function, …): PHP before 8.0 can't parse it, and the whole site goes down on activation. - No PHP 8-only syntax or functions:
match,?->, named arguments, union/mixed/statictypes, constructor promotion,str_contains()/str_starts_with()/str_ends_with(). - Sorts are not stable before PHP 8.0. Any comparator whose ties must keep an order needs an explicit tie-break (see the pinned sort in
Roadmap::get_roadmap()); 7.4 only keeps equal items in order below 17 elements, so test with more. - Dev packages must install on 7.4 (
config.platform.phpis7.4), because a site running 7.4 loadsvendor/autoload.php, including the files of dev packages when they are installed. - Check with
php -lon 7.4 and the latest PHP, and run the tests on both.
| Event | Entry point | Does |
|---|---|---|
| Activation | niroroadmap_install() → Installer::install() |
db version option; create both tables; find a page with [niroroadmap], [roadmap] or the block (SQL + shortcode regex, has_shortcode() can't work yet) or create a published "Roadmap" page, store it in roadmap_page; set the redirect transient; flag statuses pending the first time only; mark the migration done when niroroadmap_activated doesn't exist yet (fresh install — not niroroadmap_db_version, which deactivation deletes) |
| Every load | Activator::activate() |
register CPT/taxonomies, seed statuses on init 20 when pending and none exist, flush rewrite rules on init 99 once per REWRITE_VERSION, Migrator::maybe_run() on init 100, maybe_upgrade() |
| Deactivation | niroroadmap_uninstall() → Bootstrap\Uninstaller (misleading names) |
deletes niroroadmap_db_version only |
| Uninstall | uninstall.php |
always deletes the eight internal options and the niroroadmap_migrate_links cron event; with delete_on_uninstall: registers the taxonomies, force-deletes every item (meta and comments go with them), deletes all terms, drops both tables, deletes schema options and settings. The Roadmap page is always kept |
The archive slugs are roadmap-status, roadmap-product and roadmap-tag. The old product-cat, product-brand and product-tag collided with shop plugins (product-tag is WooCommerce's tag base) and only 301 now, from Controller\Front\Legacy_Urls, when nothing else answers the URL (a 404, or a feed with no queried object, since core answers any <path>/feed/ with an empty comments feed); /feed/, /feed/<type>/ and /page/N/ keep their suffix. The redirect stays for links outside the site (search engines, bookmarks, other sites).
Link migration (Bootstrap\Migrator), in the background, never asking the site owner: on the first load after an update it rewrites classic menu custom links (_menu_item_url), core/navigation-link/navigation-submenu in wp_navigation, wp_template, wp_template_part (taxonomy links from their term id), and text/block/custom HTML widgets; then WP-Cron event niroroadmap_migrate_links updates post content in batches of 100, for up to Migrator::TIME_LIMIT (20) seconds per cron run with the cursor saved after each batch, through Migrator::update_content() (keeps a revision, kses off for the write) and fires niroroadmap_archive_urls_changed at the end. A lost event is rescheduled on init while the cursor exists. Legacy_Urls::replace() touches only this site's URLs and rewrites an old URL only when a roadmap term has that slug: on 1.2.0 /product-tag/<slug>/ always showed the roadmap tag, so a stored link follows it even when WooCommerce has the same slug, while links to shop-only slugs stay as they are. Typed or bookmarked /product-tag/<slug>/ URLs belong to the shop now. Adding a migration: write it in Migrator, bump Migrator::VERSION. Changing a slug again: never reuse a shop plugin's base, bump Activator::REWRITE_VERSION so sites flush, and add the old base to Legacy_Urls::SLUGS.
Deleting an item for good also deletes its vote rows and status log (deleted_post hooks in Common\Init and Common\Status_History).
- Version bump: header
Version,NIROROADMAP_VERSION, readme.txtStable tag, changelog and Upgrade Notice.block.jsonkeeps its own0.1.0. composer release: cleanrelease/andbuild/,npm run build:blocks, makepot,composer install --no-dev -o, rsync minus.distignoreintorelease/niroroadmap/, ziprelease/niroroadmap.zip(top-levelniroroadmap/folder), thencomposer installagain to restore dev deps..github/workflows/wp-svn-release.yml: a pushedv*tag checks header and Stable tag, installs--no-dev, builds the block (fails withoutbuild/blocks-manifest.php), syncs trunk (.distignore) andsvn-assets/→ SVNassets/, copies trunk totags/<version>and commits. It refuses an existing SVN tag. Pushing a tag publishes to every user..distignorekeepsCLAUDE.md,.claude/, tests,svn-assets/,readme.mdand build tooling out of the zip and SVN.svn-assets/blueprints/blueprint.json(Playground demo, linked from readme.md) installs the WordPress.org release and callsSettings::update(),Model\FieldsandModel\Status_Logdirectly — renaming those breaks the demo.
readme.txt (WordPress.org: features, settings, shortcode attributes, hooks, REST, privacy, FAQ, changelog) and
readme.md (GitHub: shortcode table, REST table, developer notes). New settings, attributes, hooks, routes or stored
data change both. Never put issue or PR numbers in the changelog.
- Dead code:
niroroadmap_settings_menus(),niroroadmap_product_post_type(),niroroadmap_home_url();Utility::format_date(),pri(),get_option();Traits\Rest::register_route(); traitsCacheandLimiter;Activator::set_cron()is empty;use NiroRoadmap\Model\Databasein Installer and Uninstaller names a class that doesn't exist;assets/admin/js/init.js,settings.js,css/settings.cssand the#niroroadmap-settings-*rules inadmin/css/style.cssbelong to an old settings UI. - The board query doesn't exclude password-protected items, but the popup API does (404 "Task not found").
- The custom CSS description says it loads only on roadmap pages;
Front::add_assets()loads it withstyle.cssandscript.json every front-end page. script.jshas two untranslated strings: "Loading…" and "Could not load details.".