[DOC-13702]: Write documentation for the Release Note Generator

Tidying up the text.

Author: RayOffiah

home/modules/contribute/pages/release-note-generator/adding-a-new-product.adoc

@@ -24,6 +24,9 @@ alter the Python script itself. Adding a new product involves two steps:
 . Add the new product release set to `cb_release_notes_config.yaml`.
 . Create a new Jinja template for rendering the AsciiDoc file for your new release note.
 
+
+== Adding a new product
+
 To demonstrate this process, we're going to create a new release note configuration for the Sync Gateway product.
 
 NOTE: You should run the following commands from the directory where your Release Notes Generator is installed.
@@ -91,6 +94,7 @@ release_settings:
 Now, you add the URL and the JQL statements used to retrieve the Jira tickets that match your parameters:
 
 [source, yaml]
+.Adding the JQL statement
 ----
 release_settings:
   - name: "Sync Gateway"
@@ -105,17 +109,71 @@ release_settings:
         type: file
         message: 'Enter the file path for the release notes:'
     url: https://jira.issues.couchbase.com
-    jql: project = CBG AND issuetype in (Bug, "New Feature") #<.>
-      AND (fixVersion = {{release_number}} OR labels IN (known_issue)) #<.>
-      ORDER BY key ASC #<.>
+    jql: project = CBG AND issuetype in (Bug, "New Feature", Improvement) # <.>
+      AND (fixVersion = {{release_number}} OR labels IN (known_issue)) # <.>
+      ORDER BY key ASC # <.>
+    template: sync-gateway.jinja2
 ----
-
 <.> Note that the JQL statement restricts the query to tickets belonging to the Sync Gateway project,
 and also ensures that the ticket is either a Bug or a New Feature.
 <.> We supply the `release_number` parameter to the JQL statement so that we only pick up tickets from the specified release.
 <.> The `ORDER BY key` clause ensures that the tickets are returned in ascending order based on their Jira key.
 This is important to ensure that the tickets are passed to the template in the correct order.
 
+[#define-release-note-field]
+=== Step {counter: step}: Define the release note field.
+
+The script needs to know which field in a Jira ticket holds the release note description.
+The script uses this to ensure that the ticket's release note description field has been filled in.
+If the field hasn't been filled in,
+the script can optionally use AI to generate a release note summary from the
+ticket and comments.
+For most of the Couchbase projects, this was added some time after the Jira system was set up,
+so the new field was added as a custom field called `customfield_11402`.
+
+[source,yaml, subs="+quotes"]
+----
+  - name: "Sync Gateway"
+    fields:
+      - name: release_number
+        type: text
+        message: 'Enter the release number:'
+      - name: release_date
+        type: text
+        message: 'Enter the release date (Month Year):'
+      - name: file_path
+        type: file
+        message: 'Enter the file path for the release notes:'
+    url: https://jira.issues.couchbase.com
+    jql: project = CBG AND issuetype in (Bug, "New Feature", Improvement)
+      AND (fixVersion = {{release_number}} OR labels IN (known_issue))
+      ORDER BY key ASC
+    #release_note_field: 'customfield_11402'#
+    template: sync-gateway.jinja2
+----
+
+Any item from the `fields` list can be designated as a `release_note_field` (e.g. the ticket's `summary` field).
+Alternatively, if the project doesn't have a release note field, then set `release_note_field` to `None`.
+
+.Retrieving JIRA field names
+****
+The field names for Jira often differ from the names displayed on the ticket's page.
+
+The easiest way to get the field names is to
+use the `CURL` and `jq` commands to retrieve an existing ticket with a public security level:
+
+[source,shell, subs="+quotes"]
+----
+curl -X GET --location "https://jira.issues.couchbase.com/rest/api/2/issue/CBG-4977" \
+    -H "Authorization: Basic #<insert your JIRA token here>#" \
+    -H "Content-Type: application/json" | jq
+----
+
+This will render the complete ticket (including field names) to the standard output.
+****
+
+
+
 [#define-your-jinja-template]
 === Step {counter: step}: Define your JINJA template
 
@@ -144,7 +202,7 @@ release_settings:
     template: sync-gateway.jinja2
 ----
 
-Step {counter: step}: Create your JINJA template
+=== Step {counter: step}: Create your JINJA template
 
 The templates reside in the `templates` directory, as defined near the top of the configuration file.
 Use your editor to create a new template file in this directory. The file should be called `sync-gateway.jinja2`,

home/modules/contribute/pages/release-note-generator/design-guide.adoc

@@ -128,7 +128,7 @@ image::release-note-generator/cb-release-notes-menu-options.png[Release Notes Ge
 
 In the following steps, we'll look at the release set options in more detail.
 
-== Step {counter:flow}: Get the parameters
+=== Step {counter:flow}: Get the parameters
 
 In this example, assume that the user has selected the first menu option: `Fixes and enhancements (Server 8.0+)`.
 The script will then load the release set configuration for the selected product:
@@ -235,6 +235,24 @@ Pay close attention to the field parameters delimited by `{{}}`;
 these are the named parameters that will be replaced with the values
 entered by the user from the xref:#fields[`fields`] section.
 
+=== Step {counter:flow}: Set the release note field
+
+The `release_note_field` tells the generator script where the Jira ticket it will find the release note information.
+
+[source, yaml]
+----
+release_note_field: 'customfield_11402'
+----
+
+Here, we have informed the script that it will find the release note details in field `customfield_11402` in the Jira ticket.
+The release note script makes use of `release_note_field` to determine whether the ticket has its release note filled in.
+If not, then the script can fill in the missing release notes using AI.
+
+You can also reference the release note field in your Jinja template using `user_settings.release_set.release_note_field`.
+(For more information on Jinja templates, see the xref:./adding-a-new-product.adoc#define-release-note-field[Defining the  release note field].)
+
+
+
 === Step {counter:flow}: Render the release note
 
 Having retrieved the tickets that match the JQL,