Bug 598014: Document how to mark the initial comment as private when using Bug.create()

Bugzilla/Bug.pm

@@ -260,6 +260,7 @@ use constant FIELD_MAP => {
     blocks           => 'blocked',
     is_confirmed     => 'everconfirmed',
     cc_accessible    => 'cclist_accessible',
+    commentprivacy   => 'comment_is_private',
     creation_time    => 'creation_ts',
     creator          => 'reporter',
     description      => 'comment',
@@ -1405,7 +1406,7 @@ sub _check_comment {
     }
 
     # Load up some data
-    my $isprivate = $params->{commentprivacy};
+    my $isprivate = delete $params->{comment_is_private};
     my $timestamp = $params->{creation_ts};
 
     # Create the new comment so we can check it
@@ -1420,9 +1421,6 @@ sub _check_comment {
         $comment->{isprivate} = $isprivate;
     }
 
-    # Don't need this anymore as it is now in the comment hash
-    delete $params->{commentprivacy};
-
     # Validate comment. We have to do this special as a comment normally
     # requires a bug to be already created. For a new bug, the first comment
     # obviously can't get the bug if the bug is created after this

Bugzilla/WebService/Bug.pm

@@ -2244,6 +2244,9 @@ don't want it to be assigned to the component owner.
 
 =item C<cc> (array) - An array of usernames to CC on this bug.
 
+=item C<comment_is_private> (boolean) - If set to true, the description
+is private, otherwise it is assumed to be public.
+
 =item C<groups> (array) - An array of group names to put this
 bug into. You can see valid group names on the Permissions
 tab of the Preferences screen, or, if you are an administrator,
@@ -2322,6 +2325,10 @@ B<Required>, due to a bug in Bugzilla.
 Bugzilla 4.0, bugs were only added into Mandatory groups by this
 method.
 
+=item The C<comment_is_private> argument was added in Bugzilla B<4.0>.
+Before Bugzilla 4.0, you had to use the undocumented C<commentprivacy>
+argument.
+
 =back
 
 =back

enter_bug.cgi

@@ -452,14 +452,14 @@ if ($cloned_bug_id) {
     my $bug_desc = $cloned_bug->comments({ order => 'oldest_to_newest' })->[0];
     my $isprivate = $bug_desc->is_private;
 
-    $vars->{'comment'}        = "";
-    $vars->{'commentprivacy'} = 0;
+    $vars->{'comment'} = "";
+    $vars->{'comment_is_private'} = 0;
 
     if (!$isprivate || Bugzilla->user->is_insider) {
         # We use "body" to avoid any format_comment text, which would be
         # pointless to clone.
-        $vars->{'comment'}        = $bug_desc->body;
-        $vars->{'commentprivacy'} = $isprivate;
+        $vars->{'comment'} = $bug_desc->body;
+        $vars->{'comment_is_private'} = $isprivate;
     }
 
 } # end of cloned bug entry form
@@ -484,7 +484,7 @@ else {
     $vars->{'cc'}             = join(', ', $cgi->param('cc'));
 
     $vars->{'comment'}        = formvalue('comment');
-    $vars->{'commentprivacy'} = formvalue('commentprivacy');
+    $vars->{'comment_is_private'} = formvalue('comment_is_private');
 
 } # end of normal/bookmarked entry form
 

post_bug.cgi

@@ -129,7 +129,7 @@ push(@bug_fields, qw(
 
     alias
     blocked
-    commentprivacy
+    comment_is_private
     bug_file_loc
     bug_severity
     bug_status
@@ -184,7 +184,7 @@ if (defined $cgi->param('version')) {
 
 # Add an attachment if requested.
 if (defined($cgi->upload('data')) || $cgi->param('attach_text')) {
-    $cgi->param('isprivate', $cgi->param('commentprivacy'));
+    $cgi->param('isprivate', $cgi->param('comment_is_private'));
 
     # Must be called before create() as it may alter $cgi->param('ispatch').
     my $content_type = Bugzilla::Attachment::get_content_type();

process_bug.cgi

@@ -265,7 +265,7 @@ if (should_set('keywords')) {
 if (should_set('comment')) {
     $set_all_fields{comment} = {
         body       => scalar $cgi->param('comment'),
-        is_private => scalar $cgi->param('commentprivacy'),
+        is_private => scalar $cgi->param('comment_is_private'),
     };
 }
 if (should_set('see_also')) {

template/en/default/bug/create/create.html.tmpl

@@ -588,9 +588,9 @@ TUI_hide_default('attachment_text_field');
       <th>&nbsp;</th>
       <td colspan="3">
         &nbsp;&nbsp;
-        <input type="checkbox" id="commentprivacy" name="commentprivacy"
-          [% " checked=\"checked\"" IF commentprivacy %]>
-        <label for="commentprivacy">
+        <input type="checkbox" id="comment_is_private" name="comment_is_private"
+          [% ' checked="checked"' IF comment_is_private %]>
+        <label for="comment_is_private">
           Make description private (visible only to members of the 
           <strong>[% Param('insidergroup') FILTER html %]</strong> group)
         </label>

template/en/default/bug/edit.html.tmpl

@@ -1066,7 +1066,7 @@
         <u>C</u>omments</b></label>:
 
       [% IF user.is_insider %]
-        <input type="checkbox" name="commentprivacy" value="1"
+        <input type="checkbox" name="comment_is_private" value="1"
                id="newcommentprivacy"
                onClick="updateCommentTagControl(this, form)">
         <label for="newcommentprivacy">

template/en/default/bug/process/midair.html.tmpl

@@ -94,7 +94,8 @@ You have the following choices:
         <input type="hidden" name="id" value="[% cgi.param("id") FILTER html %]">
         <input type="hidden" name="delta_ts" value="[% bug.delta_ts FILTER html %]">
         <input type="hidden" name="comment" value="[% cgi.param("comment") FILTER html %]">
-        <input type="hidden" name="commentprivacy" value="[% cgi.param("commentprivacy") FILTER html %]">
+        <input type="hidden" name="comment_is_private"
+               value="[% cgi.param("comment_is_private") FILTER html %]">
         <input type="hidden" name="longdesclength" value="[% bug.comments.size %]">
         <input type="hidden" name="token" value="[% cgi.param("token") FILTER html %]">
         <input type="submit" id="process_comment" value="Submit only my new comment">

template/en/default/list/edit-multiple.html.tmpl

@@ -297,7 +297,7 @@
 
 <b><label for="comment">Additional Comments:</label></b>
 [% IF user.is_insider %]
-  <input type="checkbox" name="commentprivacy" value="1"
+  <input type="checkbox" name="comment_is_private" value="1"
          id="newcommentprivacy"
          onClick="updateCommentTagControl(this, form)"/>
    <label for="newcommentprivacy">