filled the "backward incompatibilities" section. #9670

doc/release-notes/5.14-release-notes.md

@@ -1,5 +1,7 @@
 # Dataverse Software 5.14
 
+**TODO: guides preview links need to be updated to the proper 5.14 urls before it goes live**
+
 This release brings new features, enhancements, and bug fixes to the Dataverse software. Thank you to all of the community members who contributed code, suggestions, bug reports, and other assistance across the project.
 
 Please note that, as an experiment, the sections of this release note are organized in a different order. The Upgrade and Installation sections are at the top, with the detailed sections highlighting new features and fixes further down. 
@@ -82,13 +84,11 @@ If you are running an English-only installation, you are finished with the citat
      
 - Restart Solr instance (usually service solr start, depending on solr/OS)
 
-8\. Run ReExportAll to update dataset metadata exports
-
-Follow the directions in the [Admin Guide](http://guides.dataverse.org/en/5.14/admin/metadataexport.html#batch-exports-through-the-api)
+8\. Run ReExportAll to update dataset metadata exports. Follow the directions in the [Admin Guide](http://guides.dataverse.org/en/5.14/admin/metadataexport.html#batch-exports-through-the-api).
 
 ## New JVM Options and MicroProfile Config Options
 
-The following PID provider settings are now available. See the section "Changes to PID Provider JVM Settings" below for more information. 
+The following PID provider options are now available. See the section "Changes to PID Provider JVM Settings" below for more information. 
 
 - `dataverse.pid.datacite.mds-api-url`
 - `dataverse.pid.datacite.rest-api-url`
@@ -126,7 +126,21 @@ The JVM/MicroProfile setting for handling of support emails ("Contact Email Impr
 
 ## Backward Incompatibilities
 
-**TODO: (L.A.)**
+The following list of potential backward incompatibilities references the sections of the "Detailed Release Highlights..." portion of the document further below where the corresponding changes are explained in detail.
+
+### using the new External Exporters framework
+
+Care should be taken when replacing Dataverse's internal metadata export formats as third party code, including other third party Exporters may depend on the contents of those export formats. When replacing an existing format, one must also remember to delete the cached metadata export files or run the reExport command for the metadata exports of existing datasets to be updated.
+
+See "Mechanism Added for Adding External Exporters". 
+
+### Publishing via API 
+
+When publishing a dataset via API, it now mirrors the UI behavior by requiring that the dataset has either a standard license configured, or has valid Custom Terms of Use (if allowed by the instance). Attempting to publish a dataset without such **will fail with an error message**. 
+
+See "Handling of license information fixed in the API" for guidance on how to ensure that datasets created or updated via native API have a license configured.
+
+
 
 ## Detailed Release Highlights, New Features and Use Case Scenarios
 
@@ -155,11 +169,6 @@ Performance tweaks include indexing of the datasets in the background and optimi
 
 This is enabled via the new setting `:MDCStartDate` that specifies the cutoff date. If a dataset has any legacy access counts collected prior to that date, those numbers will be displayed in addition to the any MDC numbers recorded since then. (PR #6543)
 
-### An API endpoint for deleting a file is finally available
-
-**TODO: move under "other fixes"**
-Support for deleting files using native API: http://preview.guides.gdcc.io/en/develop/api/native-api.html#deleting-files (PR #9383)
-
 ### Changes to PID Provider JVM Settings
 
 In prepration for a future feature to use multiple PID providers at the same time, all JVM settings for PID providers
@@ -235,8 +244,6 @@ It is now possible for third parties to develop and share code to provide new me
 
 #### Backward Incompatibilities
 
-**TODO: add below**
-
 Care should be taken when replacing Dataverse's internal metadata export formats as third party code, including other third party Exporters may depend on the contents of those export formats. When replacing an existing format, one must also remember to delete the cached metadata export files or run the reExport command for the metadata exports of existing datasets to be updated.
 
 #### New JVM/MicroProfile Settings
@@ -245,11 +252,11 @@ dataverse.spi.export.directory - specifies a directory, readable by the Datavers
 
 ### Contact Email Improvements
 
-Email sent from the contact forms to the contact(s) for a collection, dataset, or datafile can now optionally be cc'd to a support email address. The support email address can be changed from the default :SystemEmail address to a separate :SupportEmail address. When multiple contacts are listed, the system will now send one email to all contacts (with the optional cc if configured) instead of separate emails to each contact. Contact names with a comma that refer to Organizations will no longer have the name parts reversed in the email greeting. A new protected feedback API has been added. (PR #9204)
+Email sent from the contact forms to the contact(s) for a collection, dataset, or datafile can now optionally be cc'd to a support email address. The support email address can be changed from the default :SystemEmail address to a separate :SupportEmail address. When multiple contacts are listed, the system will now send one email to all contacts (with the optional cc if configured) instead of separate emails to each contact. Contact names with a comma that refer to Organizations will no longer have the name parts reversed in the email greeting. A new protected feedback API has been added. (PR #9186)
 
 #### Backward Incompatibilities
 
-**TODO: add to the backward incompatibilities section**
+**TODO: double-check if this is really a "backward incompatibility"; if it is, add to that section**
 When there are multiple contacts, the system will now send one email with all of the contacts in the To: header instead of sending one email to each contact (with no indication that others have been notified).
 
 #### New JVM/MicroProfile Settings
@@ -259,9 +266,9 @@ dataverse.mail.cc-support-on-contact-emails - include the support email address
 
 ### Support for Grouping Dataset Files by Folder and Category Tag
 
-Dataverse now supports grouping dataset files by folder and/or optionally by Tag/Category. The default for whether to order by folder can be changed via :OrderByFolder. Ordering by category must be enabled by an administrator via the :CategoryOrder parameter which is used to specify which tags appear first (e.g. to put Documentation files before Data or Code files, etc.) These Group-By options work with the existing sort options, i.e. sorting alphabetically means that files within each folder or tag group will be sorted alphabetically. :AllowUsersToManageOrdering can be set to true to allow users to turn folder ordering and category ordering (if enabled) on or off in the current dataset view.
+Dataverse now supports grouping dataset files by folder and/or optionally by Tag/Category. The default for whether to order by folder can be changed via :OrderByFolder. Ordering by category must be enabled by an administrator via the :CategoryOrder parameter which is used to specify which tags appear first (e.g. to put Documentation files before Data or Code files, etc.) These Group-By options work with the existing sort options, i.e. sorting alphabetically means that files within each folder or tag group will be sorted alphabetically. :AllowUsersToManageOrdering can be set to true to allow users to turn folder ordering and category ordering (if enabled) on or off in the current dataset view. (PR #9204)
 
-#### New Setting
+#### New Settings
 
 :CategoryOrder - a comma separated list of Category/Tag names defining the order in which files with those tags should be displayed. The setting can include custom tag names along with the pre-defined defaults ( Documentation, Data, and Code, which can be overridden by the ::FileCategories setting.)
 :OrderByFolder - defaults to true - whether to group files in the same folder together
@@ -311,8 +318,6 @@ For details, see #9374, <https://github.com/jupyterhub/repo2docker/issues/1242>,
 
 (PR #9568)
 
-**TODO: add this under "backward incompatibility"**
-
 When publishing a dataset via API, it now requires the dataset to either have a standard license configured, or have valid Custom Terms of Use (if allowed by the instance). Attempting to publish a dataset without such **will fail with an error message**. This introduces a backward incompatibility, and if you have scripts that automatically create, update and publish datasets, this last step may start failing. Because, unfortunately, there were some problems with the datasets APIs that made it difficult to manage licenses, so an API user was likely to end up with a dataset missing either of the above. In this release we have addressed it by making the following fixes:
 
 We fixed the incompatibility between the format in which license information was *exported* in json, and the format the create and update APIs were expecting it for *import* (https://github.com/IQSS/dataverse/issues/9155). This means that the following json format can now be imported:
@@ -341,6 +346,7 @@ Please see the [Update Metadata For a Dataset](https://guides.dataverse.org/en/l
 
 ### Changes and fixes in this release not already mentioned above include:
 
+- An endpoint for deleting a file has been added to the native API: http://preview.guides.gdcc.io/en/develop/api/native-api.html#deleting-files (PR #9383)
 - A date column has been added to the restricted file access request overview, indicating when the earliest request by that user was made. An issue was fixed where where the request list was not updated when a request was approved or rejected. (PR #9257)
 - A feature flag called "api-session-auth" has been added temporarily to aid in the development of the new frontend (#9063) but will be removed once bearer tokens (#9229) have been implemented. There is a security risk (CSRF) in enabling this flag! Do not use it in production! For more information, see http://preview.guides.gdcc.io/en/develop/installation/config.html#feature-flags
 - Changes made in v5.13 and v5.14 in multiple PRs to improve the embedded Schema.org metadata in dataset pages will only be propagated to the Schema.Org JSON-LD metadata export if a reExportAll() is done. (PR #9102)
@@ -355,8 +361,6 @@ Please see the [Update Metadata For a Dataset](https://guides.dataverse.org/en/l
 - Direct upload via the Dataverse UI will now support any algorithm configured via the `:FileFixityChecksumAlgorithm` setting. External apps using the direct upload API can now query Dataverse to discover which algorithm should be used. Sites that have been using an algorithm other than MD5 and direct upload and/or dvwebloader may want to use the `/api/admin/updateHashValues` call (see https://guides.dataverse.org/en/latest/installation/config.html?highlight=updatehashvalues#filefixitychecksumalgorithm) to replace any MD5 hashes on existing files. (PR #9482)
 
 
-
-
 ## Complete List of Changes
 
 For the complete list of code changes in this release, see the [5.14 milestone](https://github.com/IQSS/dataverse/milestone/108?closed=1) on GitHub.