add docs for "release-notes" directory experiment #5284

doc/release-notes/README.md

@@ -0,0 +1,12 @@
+# Dataverse Release Notes
+
+doc/sphinx-guides/source/developers/making-releases.rst documents the official process for making release notes but as indicated there, we are experimenting with a process with the following goals:
+
+- As a developer, I want to express in my pull request when an addition to the release notes will be necessary.
+- As a developer, I want to be aware of changes that should be made to my dev environment after a pull request has been merged. I already know to look in `scripts/database/upgrades` if I pull the latest code from the "develop" branch for updates as described in doc/sphinx-guides/source/developers/sql-upgrade-scripts.rst but I want a place to look for non-SQL updates that are required. These could be Solr schema changes or curl commands to reload metadata blocks, for example.
+
+# release-notes directory process
+
+- Create a Markdown file named after your branch (assuming your branch starts with an issue number as requested in doc/sphinx-guides/source/developers/version-control.rst) such as "5053-apis-custom-homepage.md".
+- In the file you created, give instructions for non-SQL upgrade steps that must be taken to run the branch in your pull request. Examples include Solr schema updates or reloading metadata blocks.
+- At release time, gather all the files into final release notes and make a `git rm` commit to delete them to prevent clutter.

doc/sphinx-guides/source/developers/making-releases.rst

@@ -29,6 +29,8 @@ Create a draft release at https://github.com/IQSS/dataverse/releases/new
 - The "tag version" and "title" should be the number of the milestone with a "v" in front (i.e. v4.6.2).
 - For the description, follow previous examples at https://github.com/IQSS/dataverse/releases
 
+Please note that the current process involves copying and pasting a running Google doc into release notes but we are conducting an experiment whereby developers can express the need for an addition to release notes by creating a file in ``/doc/release-notes`` containing the name of the issue they're working on. Perhaps the name of the branch could be used for the filename with ".md" appended (release notes are written in Markdown) such as ``5053-apis-custom-homepage.md``. To avoid accumulating many stale files over time, when a release is cut these files should probably be removed with ``git rm``. This experiment may help inform a future experiment having to do with improvements to our process for writing SQL upgrade scripts. See the :doc:`sql-upgrade-scripts` section for more on this topic.
+
 Make Artifacts Available for Download
 -------------------------------------
 

doc/sphinx-guides/source/developers/sql-upgrade-scripts.rst

@@ -30,6 +30,8 @@ If no SQL upgrade script exists, look at https://github.com/IQSS/dataverse/miles
 
 As with any task related to Dataverse development, if you need any help writing SQL upgrade scripts, please reach out using any of the channels mentioned under "Getting Help" in the :doc:`intro` section.
 
+Please note that we are aware of the problem of merge conflicts in the SQL update script as well as how the next version number can change at any time. Please see the :doc:`making-releases` section for how we are running an experiment having to do with release notes that might help inform an improvement of our process for developing SQL upgrade scripts.
+
 Communicating the Need to Run SQL Updates
 -----------------------------------------