provide guidance on running SQL upgrade scripts and do a little reorg

PULL_REQUEST_TEMPLATE.md

@@ -15,7 +15,7 @@ Welcome! New contributors should at least glance at [CONTRIBUTING.md](/CONTRIBUT
 - [ ] Merged latest from "develop" [branch][] and resolved conflicts
 
 [tests]: http://guides.dataverse.org/en/latest/developers/testing.html
-[SQL updates]: https://github.com/IQSS/dataverse/tree/develop/scripts/database/upgrades
+[SQL updates]: http://guides.dataverse.org/en/latest/developers/sql-upgrade-scripts.html
 [Solr updates]: https://github.com/IQSS/dataverse/blob/develop/conf/solr/7.3.0/schema.xml
 [docs]: http://guides.dataverse.org/en/latest/developers/documentation.html
 [branch]: http://guides.dataverse.org/en/latest/developers/branching-strategy.html

doc/sphinx-guides/source/developers/index.rst

@@ -16,6 +16,7 @@ Developer Guide
    tips
    troubleshooting
    version-control
+   sql-upgrade-scripts
    testing
    documentation
    debugging

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

@@ -36,7 +36,7 @@ Upload the following artifacts to the draft release you created:
 
 - war file (``mvn package`` from Jenkins)
 - installer (``cd scripts/installer && make``)
-- database migration script
+- database migration script (see also the :doc:`sql-upgrade-scripts` section)
 - other files as needed, such as an updated Solr schema
 
 Publish Release

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

@@ -0,0 +1,40 @@
+===================
+SQL Upgrade Scripts
+===================
+
+The database schema for Dataverse is constantly evolving. As other developers make changes to the database schema you will need to keep up with these changes to have your development environment in working order. Additionally, as you make changes to the database schema, you must write SQL upgrade scripts when needed and communicate with your fellow developers about applying those scripts.
+
+.. contents:: |toctitle|
+	:local:
+
+Location of SQL Upgrade Scripts
+-------------------------------
+
+``scripts/database/upgrades`` is the directory where we keep or SQL upgrade scripts.
+
+How to Determine if You Need to Create or Update a SQL Upgrade Script
+---------------------------------------------------------------------
+
+If you are creating a new database table (which maps to an ``@Entity`` in JPA), you do not need to create or update a SQL upgrade script. The reason for this is that we use ``create-tables`` in ``src/main/resources/META-INF/persistence.xml`` so that new tables are automatically created by Glassfish when you deploy your war file.
+
+If you are doing anything other than creating a new database table such as adding a column to an existing table, you must create or update a SQL upgrade script.
+
+How to Create or Update a SQL Upgrade Script
+--------------------------------------------
+
+We assume you have already read the :doc:`version-control` section and have been keeping your feature branch up to date with the "develop" branch.
+
+First, check https://github.com/IQSS/dataverse/tree/develop/scripts/database/upgrades to see if a SQL upgrade script for the next release already exists. For example, if the current release is 4.9.4 and the next release will be 4.10, the script will be named ``upgrade_v4.9.4_to_v4.10.sql``. If the script exists, just add your changes to the bottom of it.
+
+If no SQL upgrade script exists, look at https://github.com/IQSS/dataverse/milestones to figure out the name of the next milestone and create a script using the naming convention above.
+
+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.
+
+Communicating the Need to Run SQL Updates
+-----------------------------------------
+
+If you have made a pull request that contains SQL updates and that pull request is merged into the "develop" branch, you are responsible for communicating to other developers that when then pull the latest code from "develop" they must run your SQL updates. Post a message to the "dataverse-dev" mailing list at https://groups.google.com/forum/#!forum/dataverse-dev
+
+----
+
+Previous: :doc:`version-control` | Next: :doc:`testing`

doc/sphinx-guides/source/developers/testing.rst

@@ -290,4 +290,4 @@ Future Work on Load/Performance Testing
 
 ----
 
-Previous: :doc:`version-control` | Next: :doc:`documentation`
+Previous: :doc:`sql-upgrade-scripts` | Next: :doc:`documentation`

doc/sphinx-guides/source/developers/tips.rst

@@ -79,7 +79,7 @@ For faster iteration while working on JSF pages, it is highly recommended that y
 Database Schema Exploration
 ---------------------------
 
-With over 100 tables, the Dataverse PostgreSQL database ("dvndb") can be somewhat daunting for newcomers. Here are some tips for coming up to speed.
+With over 100 tables, the Dataverse PostgreSQL database ("dvndb") can be somewhat daunting for newcomers. Here are some tips for coming up to speed. (See also the :doc:`sql-upgrade-scripts` section.)
 
 pgAdmin
 ~~~~~~~~

doc/sphinx-guides/source/developers/version-control.rst

@@ -145,4 +145,4 @@ GitHub documents how to make changes to a fork at https://help.github.com/articl
 
 ----
 
-Previous: :doc:`troubleshooting` | Next: :doc:`testing`
+Previous: :doc:`troubleshooting` | Next: :doc:`sql-upgrade-scripts`

scripts/database/upgrades/upgrade_v4.9.4_to_v4.10.sql

@@ -1,4 +1,6 @@
 ALTER TABLE usernotification
 ADD requestor_id BIGINT;
+ALTER TABLE datasetfieldtype ADD COLUMN uri text;
+ALTER TABLE metadatablock ADD COLUMN namespaceuri text;