From b80e93cc7cf4515fb336c031c28888c4dee2c555 Mon Sep 17 00:00:00 2001
From: joedolson <joedolson@git.wordpress.org>
Date: Tue, 3 Sep 2024 20:45:16 +0000
Subject: [PATCH] Docs: Add changing existing items recommendations to
 'admin_bar_menu' action.

Improves the `'admin_bar_menu'` docblock by adding recommendations for customizing / changing existing items.

It also improves the `wp_admin_bar_render()` function's docblock by removing the "most optimal point" sentence.

The [58748] changeset moved the user menu to a higher priority level (of `9991`) to achieve:

> so nodes added with higher priorities will still be shown visually before the user and recovery menu items, as they were prior to [58215].

When hooking into `'admin_bar_menu'` with a priority level less than 9991 and attempting to get the `'my-account'` node, `null` is returned. While the preferred approach is to hook into `'wp_before_admin_bar_render'`, the documentation of the `'admin_bar_menu'` action was previously misleading.

Follow-up to [58748], [58759].

Reviewed by joedolson.
Merges [58978] to the 6.6 branch.

Props michaelwp85, narenin, sabernhardt, joedolson, costdev, jorbin, hellofromTonya, mukesh27, pbiron.
Fixes #61738.
Built from https://develop.svn.wordpress.org/branches/6.6@58982


git-svn-id: http://core.svn.wordpress.org/branches/6.6@58378 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/admin-bar.php | 10 ++++++----
 wp-includes/version.php   |  2 +-
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/wp-includes/admin-bar.php b/wp-includes/admin-bar.php
index 39c8a0e86b..0d7c3b63c7 100644
--- a/wp-includes/admin-bar.php
+++ b/wp-includes/admin-bar.php
@@ -62,9 +62,8 @@ function _wp_admin_bar_init() {
  * the function is also called late on {@see 'wp_footer'}.
  *
  * It includes the {@see 'admin_bar_menu'} action which should be used to hook in and
- * add new menus to the admin bar. That way you can be sure that you are adding at most
- * optimal point, right before the admin bar is rendered. This also gives you access to
- * the `$post` global, among others.
+ * add new menus to the admin bar. This also gives you access to the `$post` global,
+ * among others.
  *
  * @since 3.1.0
  * @since 5.4.0 Called on 'wp_body_open' action first, with 'wp_footer' as a fallback.
@@ -86,7 +85,10 @@ function wp_admin_bar_render() {
 	/**
 	 * Loads all necessary admin bar items.
 	 *
-	 * This is the hook used to add, remove, or manipulate admin bar items.
+	 * This hook can add, remove, or manipulate admin bar items. The priority
+	 * determines the placement for new items, and changes to existing items
+	 * would require a high priority. To remove or manipulate existing nodes
+	 * without a specific priority, use `wp_before_admin_bar_render`.
 	 *
 	 * @since 3.1.0
 	 *
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 5878a0ef91..2c0e8eaf33 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.6.2-alpha-58980';
+$wp_version = '6.6.2-alpha-58982';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.