Confluence: Support setting version message for new Confluence pages

 #1464

Author: gonchik

atlassian/confluence/server/__init__.py

@@ -912,6 +912,7 @@ def create_page(
         editor=None,
         full_width=False,
         status="current",
+        version_comment=None,
     ):
         """
         Create page from scratch
@@ -925,6 +926,7 @@ def create_page(
         :param editor: OPTIONAL: v2 to be created in the new editor
         :param full_width: DEFAULT: False
         :param status: either 'current' or 'draft'
+        :param version_comment: optional message recorded with the first page version
         :return:
         """
         log.info('Creating %s "%s" -> "%s"', type, space, title)
@@ -939,6 +941,8 @@ def create_page(
         }
         if parent_id:
             data["ancestors"] = [{"type": type, "id": parent_id}]
+        if version_comment is not None:
+            data["version"] = {"message": version_comment}
         if editor is not None and editor in ["v1", "v2"]:
             data["metadata"]["properties"]["editor"] = {"value": editor}
         if full_width is True:
@@ -1923,14 +1927,19 @@ def update_or_create(
                 full_width=full_width,
             )
         else:
+            create_kwargs = {
+                "space": space,
+                "parent_id": parent_id,
+                "title": title,
+                "body": body,
+                "representation": representation,
+                "editor": editor,
+                "full_width": full_width,
+            }
+            if version_comment is not None:
+                create_kwargs["version_comment"] = version_comment
             result = self.create_page(
-                space=space,
-                parent_id=parent_id,
-                title=title,
-                body=body,
-                representation=representation,
-                editor=editor,
-                full_width=full_width,
+                **create_kwargs,
             )
 
         log.info(

docs/confluence.rst

@@ -265,6 +265,9 @@ Page actions
     confluence.update_or_create(parent_id, title, body, representation='storage', full_width=False)
     confluence.update_or_create(title=title, body=body, space='SPACEKEY')
 
+    # Server/Data Center: annotate the first page revision on creation.
+    confluence.create_page('SPACEKEY', title, body, version_comment='Initial import')
+
     # Preserve Confluence storage macros when updating tables. Do not round-trip
     # a page containing images through pandas.read_html(...).to_html(), because
     # pandas represents embedded image cells as missing values and serializes

tests/confluence/test_confluence_server.py

@@ -67,6 +67,14 @@ def test_bad_request_includes_a_bounded_non_json_response(self, confluence_serve
         with pytest.raises(HTTPError, match="Malformed XHTML near the table macro"):
             confluence_server.raise_for_status(response)
 
+    @patch.object(ConfluenceServer, "post")
+    def test_create_page_includes_first_version_comment(self, mock_post, confluence_server):
+        mock_post.return_value = {"id": "123"}
+
+        confluence_server.create_page("TEAM", "Report", "<p>Body</p>", version_comment="Initial import")
+
+        assert mock_post.call_args.kwargs["data"]["version"] == {"message": "Initial import"}
+
     @patch.object(ConfluenceServer, "_get_paged")
     def test_get_all_page_versions_follows_paginated_history(self, mock_get_paged, confluence_server):
         mock_get_paged.return_value = iter([{"number": 2}, {"number": 1}])
@@ -359,6 +367,19 @@ def test_update_or_create_creates_top_level_page_with_explicit_space(
             full_width=False,
         )
 
+    @patch.object(ConfluenceServer, "create_page")
+    @patch.object(ConfluenceServer, "page_exists", return_value=False)
+    def test_update_or_create_passes_version_comment_when_creating(
+        self, mock_page_exists, mock_create_page, confluence_server
+    ):
+        mock_create_page.return_value = {"id": "123", "_links": {"tinyui": "/x/abc"}}
+
+        confluence_server.update_or_create(
+            title="Top level", body="<p>Body</p>", space="TEAM", version_comment="Initial import"
+        )
+
+        assert mock_create_page.call_args.kwargs["version_comment"] == "Initial import"
+
     def test_update_or_create_requires_space_for_a_top_level_page(self, confluence_server):
         with pytest.raises(ApiValueError, match="space is required"):
             confluence_server.update_or_create(title="Top level", body="<p>Body</p>")