From 092ea01af583670aebbf66fae659c293ca6a037d Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Tue, 6 Nov 2018 16:12:23 -0500 Subject: [PATCH] add docs for "release-notes" directory experiment #5284 --- doc/release-notes/README.md | 12 ++++++++++++ .../source/developers/making-releases.rst | 2 ++ .../source/developers/sql-upgrade-scripts.rst | 2 ++ 3 files changed, 16 insertions(+) create mode 100644 doc/release-notes/README.md diff --git a/doc/release-notes/README.md b/doc/release-notes/README.md new file mode 100644 index 00000000000..8c2d5748034 --- /dev/null +++ b/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. diff --git a/doc/sphinx-guides/source/developers/making-releases.rst b/doc/sphinx-guides/source/developers/making-releases.rst index 9782366b61d..7ded5f66a04 100755 --- a/doc/sphinx-guides/source/developers/making-releases.rst +++ b/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 ------------------------------------- diff --git a/doc/sphinx-guides/source/developers/sql-upgrade-scripts.rst b/doc/sphinx-guides/source/developers/sql-upgrade-scripts.rst index bb70c2b59c8..d50ecc0d72e 100644 --- a/doc/sphinx-guides/source/developers/sql-upgrade-scripts.rst +++ b/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 -----------------------------------------