Changeset 7471

Timestamp:

09/10/2026 01:30:04 AM (6 weeks ago)

Author:

johnjamesjacoby

Message:

Documentation: expand count compatibility notes.

Document count-hook timing for creation and moderation, custom-status integration, atomic metadata retry semantics, subforum query filters, and selective repair guidance for existing sites.

In trunk, for 2.7.

See #3678.

Location:

trunk/src

Files:

• includes/core/abstraction.php (modified) (1 diff)
• includes/forums/functions.php (modified) (1 diff)
• readme.txt (modified) (3 diffs)

trunk/src/includes/core/abstraction.php

@@ -163 +163 @@
  * to run. Existing metadata uses a conditional database update while preserving
  * the standard update metadata short-circuit filter and before/after actions.
+ * The short-circuit filter runs once against the first sanitized candidate.
  * Before actions run for every conditional attempt, while after actions run
  * only after a successful write. Metadata caches are cleared between attempts

trunk/src/includes/forums/functions.php

@@ -2887 +2887 @@
  *
  * @since 2.0.0 bbPress (r2908)
- * @since 2.6.16 Exclude forums with uncountable statuses.
+ * @since 2.6.16 Restrict results to countable statuses instead of using
+ *               bbp_get_all_child_ids().
  *
  * @param int $forum_id Forum id.

trunk/src/readme.txt

@@ -52 +52 @@
 The existing `bbp_new_*`, `bbp_insert_*`, `bbp_trash_*`, `bbp_untrash_*`, `bbp_spam_*`, `bbp_unspam_*`, `bbp_approve_*`, and `bbp_unapprove_*` topic and reply actions continue to fire with their existing arguments and timing. Their corresponding completed actions, such as `bbp_trashed_*`, also remain available. The public count helper functions also remain callable.
 
-bbPress no longer attaches its built-in increase, decrease, and insertion count callbacks to those creation and moderation actions. Manually firing one of those actions without changing the post status therefore no longer updates counts. Extensions that need finalized counts after creation or moderation should use `bbp_transition_post_status` at priority 11 or later.
+For topic and reply creation, the status transition occurs inside `wp_insert_post()`. The later `bbp_new_*` and `bbp_insert_*` actions therefore continue to run after status counts are updated and after bbPress stores its relationship metadata. Creation-specific integrations can remain on those actions.
+
+For moderation, status-count synchronization occurs between the existing pre-transition action, such as `bbp_spam_reply`, and its completed action, such as `bbp_spammed_reply`. Extensions that need every persisted topic, reply, forum, and user status-count change should use `bbp_transition_post_status` at priority 11 or later. Completed moderation actions begin after those counts are finalized.
+
+bbPress no longer attaches its built-in topic, reply, forum, and user status-count callbacks to the creation and moderation actions. Manually firing one of those actions without changing the post status therefore no longer updates those counts. Topic voice counts and engagements remain attached to the creation and completed moderation actions, so manually firing one of those actions can still recalculate voices and engagements without a status change. The priority-11 transition hook does not observe those later updates. Extensions that need both recalculations to finish can use priority 31 or later on the legacy action; bbPress runs engagement callbacks before voice-count callbacks. Count membership comes from the filtered public and non-public status arrays. Extensions that already maintain counts for custom statuses should remove duplicate count callbacks and keep the public and non-public arrays disjoint. The public increase and decrease convenience functions now validate the current topic or reply status; use the lower-level bump functions for an intentional numeric difference. Do not manually fire `bbp_transition_post_status` to simulate a write because its count callback trusts the supplied statuses as a completed database transition.
 
 Permanent deletion does not produce a post-status transition. Its count maintenance continues through the existing `bbp_deleted_topic` and `bbp_deleted_reply` actions.
 
-Count bump functions now use conditional metadata writes and bounded retries so simultaneous requests do not overwrite each other's existing count changes. Existing bbPress count filters and the standard WordPress metadata filters and actions continue to run. WordPress metadata tables do not enforce unique object-and-key pairs, so simultaneous first-time inserts retain the same limitation as the core metadata API. The `bbp_pre_bump_count_meta` filter can short-circuit an update, the `bbp_bump_count_meta_max_attempts` filter controls the default limit of five write attempts, and the `bbp_bump_count_meta_types` filter controls the post, user, term, and comment metadata types supported by default. `bbp_update_user_topic_count()` and `bbp_update_user_reply_count()` accept an optional third `$difference` argument for this internal bump lifecycle; existing calls remain compatible.
+Count bump functions now use conditional metadata writes and bounded retries so simultaneous requests do not overwrite each other's existing count changes. Existing bbPress count filters and the standard WordPress metadata filters and actions continue to run. A before-update metadata action may run more than once when a request loses a comparison and retries; its matching after-update action runs only for the successful write. The update-metadata short-circuit filter runs once for the bump call using its first sanitized candidate value. A user-count filter that changes the absolute result retains the previous absolute-update behavior and opts that call out of the atomic difference path.
+
+WordPress metadata tables do not enforce unique object-and-key pairs, so simultaneous first-time inserts retain the same limitation as the core metadata API. A request can also exhaust the bounded retries under unusually high contention. An atomic bump applies a difference to its supplied stored or default value and is not a recount. The `bbp_pre_bump_count_meta` filter can short-circuit an update, the `bbp_bump_count_meta_max_attempts` filter controls the default limit of five write attempts, and the `bbp_bump_count_meta_types` filter controls the post, user, term, and comment metadata types supported by default. `bbp_update_user_topic_count()` and `bbp_update_user_reply_count()` accept an optional third `$difference` argument for this internal bump lifecycle; existing calls remain compatible.
 
 Post-author changes and user deletion with post reassignment now reconcile affected user contribution, topic engagement, and voice counts. Moderator move, merge, and split operations also reconcile source, destination, and ancestor forum counts. Forum count updater functions accept an optional final argument for propagating a recount's difference through ancestor totals; existing calls remain compatible. Forum reply recounts include public replies only when their parent topics are also public. A public reply beneath a non-public topic is excluded from the public forum total without being included in the pending, spammed, and trashed reply count. Topic engagement recounts honor filtered public topic and reply statuses, and preserve other term-backed relationships.
@@ -62 +68 @@
 = Subforum counts in 2.6.16 =
 
-bbPress now maintains subforum counts when forums are trashed, restored, permanently deleted, or moved between parents. Recursive forum counts include public, private, and hidden subforums while excluding subforums with uncountable statuses. The new `bbp_post_updated` action receives the post ID, the updated `WP_Post` object, and the previous `WP_Post` object after any bbPress post type is updated.
+bbPress now maintains subforum counts when forums are trashed, restored, permanently deleted, or moved between parents. Recursive forum counts include public, private, and hidden subforums while excluding subforums with uncountable statuses. `bbp_forum_query_subforum_ids()` no longer inherits the broader `bbp_get_all_child_ids` result; extensions that customized subforum count membership through that lower-level filter should use `bbp_forum_query_subforum_ids`, `bbp_get_countable_forum_statuses`, or the forum-status filters. The new `bbp_post_updated` action receives the post ID, the updated `WP_Post` object, and the previous `WP_Post` object after any bbPress post type is updated.
+
+The upgrade does not synchronously recount every forum. Sites with known stale metadata can selectively run the applicable count and engagement tools under Tools > Forums > Repair Forums. These tools can be expensive on large sites.
 
 == Screenshots ==
@@ -82 +90 @@
 = 2.6.16 =
 
-Count maintenance now uses the bbPress post-status transition action. Extensions that customize topic or reply counts should review the Developer Notes.
+Count maintenance now uses the bbPress post-status transition action and conditional metadata writes. Extensions that attach count callbacks to creation or moderation actions, add custom statuses, filter count values, or customize subforum queries should review the Developer Notes. Sites with known stale counts can selectively run the repair tools after upgrading.