Split force for publish descendants into separate options for publish unpublish and re-publish unedited (13) (#18249)

* Split force for publish descendents into separate options for publish unpublish and re-publish unedited.

* Added integration task verifying updated behaviour.

* Variant integration test.

* Update test data controller.

* Remove usued function parameters.

* Refactor to enum.

* Fixed flags enum.

* Variable name refactor.

* Applied changes from code review.

* Refactored method name.

* Aligned js boolean checks.

Author: AndyButland

src/Umbraco.Core/EmbeddedResources/Lang/en.xml

@@ -309,6 +309,7 @@
     <key alias="removeTextBox">Remove this text box</key>
     <key alias="contentRoot">Content root</key>
     <key alias="includeUnpublished">Include unpublished content items.</key>
+    <key alias="forceRepublish">Publish unchanged items.</key>
     <key alias="isSensitiveValue">This value is hidden. If you need access to view this value please contact your
       website administrator.
     </key>

src/Umbraco.Core/EmbeddedResources/Lang/en_us.xml

@@ -308,6 +308,7 @@
     <key alias="removeTextBox">Remove this text box</key>
     <key alias="contentRoot">Content root</key>
     <key alias="includeUnpublished">Include unpublished content items.</key>
+    <key alias="forceRepublish">Publish unchanged items.</key>
     <key alias="isSensitiveValue">This value is hidden. If you need access to view this value please contact your
       website administrator.
     </key>

src/Umbraco.Core/Models/ContentEditing/ContentSaveAction.cs

@@ -1,69 +1,101 @@
 namespace Umbraco.Cms.Core.Models.ContentEditing;
 
 /// <summary>
-///     The action associated with saving a content item
+///     The action associated with saving a content item.
 /// </summary>
 public enum ContentSaveAction
 {
     /// <summary>
-    ///     Saves the content item, no publish
+    ///     Saves the content item, no publish.
     /// </summary>
     Save = 0,
 
     /// <summary>
-    ///     Creates a new content item
+    ///     Creates a new content item.
     /// </summary>
     SaveNew = 1,
 
     /// <summary>
-    ///     Saves and publishes the content item
+    ///     Saves and publishes the content item.
     /// </summary>
     Publish = 2,
 
     /// <summary>
-    ///     Creates and publishes a new content item
+    ///     Creates and publishes a new content item.
     /// </summary>
     PublishNew = 3,
 
     /// <summary>
-    ///     Saves and sends publish notification
+    ///     Saves and sends publish notification.
     /// </summary>
     SendPublish = 4,
 
     /// <summary>
-    ///     Creates and sends publish notification
+    ///     Creates and sends publish notification.
     /// </summary>
     SendPublishNew = 5,
 
     /// <summary>
-    ///     Saves and schedules publishing
+    ///     Saves and schedules publishing.
     /// </summary>
     Schedule = 6,
 
     /// <summary>
-    ///     Creates and schedules publishing
+    ///     Creates and schedules publishing.
     /// </summary>
     ScheduleNew = 7,
 
     /// <summary>
-    ///     Saves and publishes the content item including all descendants that have a published version
+    ///     Saves and publishes the content item including all descendants that have a published version.
     /// </summary>
     PublishWithDescendants = 8,
 
     /// <summary>
-    ///     Creates and publishes the content item including all descendants that have a published version
+    ///     Creates and publishes the new content item including all descendants that have a published version.
     /// </summary>
     PublishWithDescendantsNew = 9,
 
     /// <summary>
     ///     Saves and publishes the content item including all descendants regardless of whether they have a published version
-    ///     or not
+    ///     or not.
     /// </summary>
+    [Obsolete("This option is no longer used as the 'force' aspect has been extended into options for publishing unpublished and re-publishing changed content. Please use one of those options instead.")]
     PublishWithDescendantsForce = 10,
 
     /// <summary>
-    ///     Creates and publishes the content item including all descendants regardless of whether they have a published
-    ///     version or not
+    ///     Creates and publishes the new content item including all descendants regardless of whether they have a published
+    ///     version or not.
     /// </summary>
+    [Obsolete("This option is no longer used as the 'force' aspect has been extended into options for publishing unpublished and re-publishing changed content. Please use one of those options instead.")]
     PublishWithDescendantsForceNew = 11,
+
+    /// <summary>
+    ///     Saves and publishes the content item including all descendants including publishing previously unpublished content.
+    /// </summary>
+    PublishWithDescendantsIncludeUnpublished = 12,
+
+    /// <summary>
+    ///     Saves and publishes the new content item including all descendants including publishing previously unpublished content.
+    /// </summary>
+    PublishWithDescendantsIncludeUnpublishedNew = 13,
+
+    /// <summary>
+    ///     Saves and publishes the content item including all descendants irrespective of whether there are any pending changes.
+    /// </summary>
+    PublishWithDescendantsForceRepublish = 14,
+
+    /// <summary>
+    ///     Saves and publishes the new content item including all descendants including publishing previously unpublished content.
+    /// </summary>
+    PublishWithDescendantsForceRepublishNew = 15,
+
+    /// <summary>
+    ///     Saves and publishes the content item including all descendants including publishing previously unpublished content and irrespective of whether there are any pending changes.
+    /// </summary>
+    PublishWithDescendantsIncludeUnpublishedAndForceRepublish = 16,
+
+    /// <summary>
+    ///     Saves and publishes the new content item including all descendants including publishing previously unpublished content and irrespective of whether there are any pending changes.
+    /// </summary>
+    PublishWithDescendantsIncludeUnpublishedAndForceRepublishNew = 17,
 }

src/Umbraco.Core/Models/PublishBranchFilter.cs

@@ -0,0 +1,28 @@
+namespace Umbraco.Cms.Core.Models;
+
+/// <summary>
+/// Describes the options available with publishing a content branch for force publishing.
+/// </summary>
+[Flags]
+public enum PublishBranchFilter
+{
+    /// <summary>
+    /// The default behavior is to publish only the published content that has changed.
+    /// </summary>
+    Default = 0,
+
+    /// <summary>
+    /// For publishing a branch, publish all changed content, including content that is not published.
+    /// </summary>
+    IncludeUnpublished = 1,
+
+    /// <summary>
+    /// For publishing a branch, force republishing of all published content, including content that has not changed.
+    /// </summary>
+    ForceRepublish = 2,
+
+    /// <summary>
+    /// For publishing a branch, publish all content, including content that is not published and content that has not changed.
+    /// </summary>
+    All = IncludeUnpublished | ForceRepublish,
+}

src/Umbraco.Core/Services/ContentService.cs

@@ -1963,17 +1963,14 @@ private bool SaveAndPublishBranch_PublishCultures(IContent content, HashSet<stri
     }
 
     // utility 'ShouldPublish' func used by SaveAndPublishBranch
-    private HashSet<string>? SaveAndPublishBranch_ShouldPublish(ref HashSet<string>? cultures, string c, bool published, bool edited, bool isRoot, bool force)
+    private HashSet<string>? SaveAndPublishBranch_ShouldPublish(ref HashSet<string>? cultures, string c, bool published, bool edited, bool isRoot, PublishBranchFilter publishBranchFilter)
     {
         // if published, republish
         if (published)
         {
-            if (cultures == null)
-            {
-                cultures = new HashSet<string>(); // empty means 'already published'
-            }
+            cultures ??= []; // empty means 'already published'
 
-            if (edited)
+            if (edited || publishBranchFilter.HasFlag(PublishBranchFilter.ForceRepublish))
             {
                 cultures.Add(c); // <culture> means 'republish this culture'
             }
@@ -1982,22 +1979,23 @@ private bool SaveAndPublishBranch_PublishCultures(IContent content, HashSet<stri
         }
 
         // if not published, publish if force/root else do nothing
-        if (!force && !isRoot)
+        if (!publishBranchFilter.HasFlag(PublishBranchFilter.IncludeUnpublished) && !isRoot)
         {
             return cultures; // null means 'nothing to do'
         }
 
-        if (cultures == null)
-        {
-            cultures = new HashSet<string>();
-        }
+        cultures ??= [];
 
         cultures.Add(c); // <culture> means 'publish this culture'
         return cultures;
     }
 
     /// <inheritdoc />
     public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool force, string culture = "*", int userId = Constants.Security.SuperUserId)
+        => SaveAndPublishBranch(content, force ? PublishBranchFilter.IncludeUnpublished : PublishBranchFilter.Default, culture, userId);
+
+    /// <inheritdoc />
+    public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, PublishBranchFilter publishBranchFilter, string culture = "*", int userId = Constants.Security.SuperUserId)
     {
         // note: EditedValue and PublishedValue are objects here, so it is important to .Equals()
         // and not to == them, else we would be comparing references, and that is a bad thing
@@ -2016,13 +2014,13 @@ public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool fo
             // invariant content type
             if (!c.ContentType.VariesByCulture())
             {
-                return SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, "*", c.Published, c.Edited, isRoot, force);
+                return SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, "*", c.Published, c.Edited, isRoot, publishBranchFilter);
             }
 
             // variant content type, specific culture
             if (culture != "*")
             {
-                return SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, culture, c.IsCulturePublished(culture), c.IsCultureEdited(culture), isRoot, force);
+                return SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, culture, c.IsCulturePublished(culture), c.IsCultureEdited(culture), isRoot, publishBranchFilter);
             }
 
             // variant content type, all cultures
@@ -2032,23 +2030,27 @@ public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool fo
                 // others will have to 'republish this culture'
                 foreach (var x in c.AvailableCultures)
                 {
-                    SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, x, c.IsCulturePublished(x), c.IsCultureEdited(x), isRoot, force);
+                    SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, x, c.IsCulturePublished(x), c.IsCultureEdited(x), isRoot, publishBranchFilter);
                 }
 
                 return culturesToPublish;
             }
 
-            // if not published, publish if force/root else do nothing
-            return force || isRoot
+            // if not published, publish if forcing unpublished/root else do nothing
+            return publishBranchFilter.HasFlag(PublishBranchFilter.IncludeUnpublished) || isRoot
                 ? new HashSet<string> { "*" } // "*" means 'publish all'
                 : null; // null means 'nothing to do'
         }
 
-        return SaveAndPublishBranch(content, force, ShouldPublish, SaveAndPublishBranch_PublishCultures, userId);
+        return SaveAndPublishBranch(content, ShouldPublish, SaveAndPublishBranch_PublishCultures, userId);
     }
 
     /// <inheritdoc />
     public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool force, string[] cultures, int userId = Constants.Security.SuperUserId)
+        => SaveAndPublishBranch(content, force ? PublishBranchFilter.IncludeUnpublished : PublishBranchFilter.Default, cultures, userId);
+
+    /// <inheritdoc />
+    public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, PublishBranchFilter publishBranchFilter, string[] cultures, int userId = Constants.Security.SuperUserId)
     {
         // note: EditedValue and PublishedValue are objects here, so it is important to .Equals()
         // and not to == them, else we would be comparing references, and that is a bad thing
@@ -2064,7 +2066,7 @@ public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool fo
             // invariant content type
             if (!c.ContentType.VariesByCulture())
             {
-                return SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, "*", c.Published, c.Edited, isRoot, force);
+                return SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, "*", c.Published, c.Edited, isRoot, publishBranchFilter);
             }
 
             // variant content type, specific cultures
@@ -2074,24 +2076,23 @@ public IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool fo
                 // others will have to 'republish this culture'
                 foreach (var x in cultures)
                 {
-                    SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, x, c.IsCulturePublished(x), c.IsCultureEdited(x), isRoot, force);
+                    SaveAndPublishBranch_ShouldPublish(ref culturesToPublish, x, c.IsCulturePublished(x), c.IsCultureEdited(x), isRoot, publishBranchFilter);
                 }
 
                 return culturesToPublish;
             }
 
-            // if not published, publish if force/root else do nothing
-            return force || isRoot
+            // if not published, publish if forcing unpublished/root else do nothing
+            return publishBranchFilter.HasFlag(PublishBranchFilter.IncludeUnpublished) || isRoot
                 ? new HashSet<string>(cultures) // means 'publish specified cultures'
                 : null; // null means 'nothing to do'
         }
 
-        return SaveAndPublishBranch(content, force, ShouldPublish, SaveAndPublishBranch_PublishCultures, userId);
+        return SaveAndPublishBranch(content, ShouldPublish, SaveAndPublishBranch_PublishCultures, userId);
     }
 
     internal IEnumerable<PublishResult> SaveAndPublishBranch(
         IContent document,
-        bool force,
         Func<IContent, HashSet<string>?> shouldPublish,
         Func<IContent, HashSet<string>, IReadOnlyCollection<ILanguage>, bool> publishCultures,
         int userId = Constants.Security.SuperUserId)

src/Umbraco.Core/Services/IContentService.cs

@@ -431,6 +431,7 @@ public interface IContentService : IContentServiceBase<IContent>
     ///         published. The root of the branch is always published, regardless of <paramref name="force" />.
     ///     </para>
     /// </remarks>
+    [Obsolete("This method is not longer used as the 'force' parameter has been extended into options for publishing unpublished and re-publishing changed content. Please use the overload containing the parameter for those options instead.")]
     IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool force, string culture = "*", int userId = Constants.Security.SuperUserId);
 
     /// <summary>
@@ -447,8 +448,47 @@ public interface IContentService : IContentServiceBase<IContent>
     ///         published. The root of the branch is always published, regardless of <paramref name="force" />.
     ///     </para>
     /// </remarks>
+    [Obsolete("This method is not longer used as the 'force' parameter has been extended into options for publishing unpublished and re-publishing changed content. Please use the overload containing the parameter for those options instead.")]
     IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, bool force, string[] cultures, int userId = Constants.Security.SuperUserId);
 
+    /// <summary>
+    ///     Saves and publishes a document branch.
+    /// </summary>
+    /// <param name="content">The root document.</param>
+    /// <param name="publishBranchFilter">A value indicating options for force publishing unpublished or re-publishing unchanged content.</param>
+    /// <param name="culture">A culture, or "*" for all cultures.</param>
+    /// <param name="userId">The identifier of the user performing the operation.</param>
+    /// <remarks>
+    ///     <para>
+    ///         Unless specified, all cultures are re-published. Otherwise, one culture can be specified. To act on more
+    ///         than one culture, see the other overloads of this method.
+    ///     </para>
+    ///     <para>
+    ///         The root of the branch is always published, regardless of <paramref name="publishBranchFilter" />.
+    ///     </para>
+    /// </remarks>
+    IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, PublishBranchFilter publishBranchFilter, string culture = "*", int userId = Constants.Security.SuperUserId)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => SaveAndPublishBranch(content, publishBranchFilter.HasFlag(PublishBranchFilter.IncludeUnpublished), culture, userId);
+#pragma warning restore CS0618 // Type or member is obsolete
+
+    /// <summary>
+    ///     Saves and publishes a document branch.
+    /// </summary>
+    /// <param name="content">The root document.</param>
+    /// <param name="publishBranchFilter">A value indicating options for force publishing unpublished or re-publishing unchanged content.</param>
+    /// <param name="cultures">The cultures to publish.</param>
+    /// <param name="userId">The identifier of the user performing the operation.</param>
+    /// <remarks>
+    ///     <para>
+    ///         The root of the branch is always published, regardless of <paramref name="publishBranchFilter" />.
+    ///     </para>
+    /// </remarks>
+    IEnumerable<PublishResult> SaveAndPublishBranch(IContent content, PublishBranchFilter publishBranchFilter, string[] cultures, int userId = Constants.Security.SuperUserId)
+#pragma warning disable CS0618 // Type or member is obsolete
+        => SaveAndPublishBranch(content, publishBranchFilter.HasFlag(PublishBranchFilter.IncludeUnpublished), cultures, userId);
+#pragma warning restore CS0618 // Type or member is obsolete
+
     ///// <summary>
     ///// Saves and publishes a document branch.
     ///// </summary>