Add documentation about how to modify NC_DISPATCH_VERSION

re: Issue Unidata#2582

Update the file netcdf-c/docs/dispatch.md to include
an appendix that discusses how to properly update the
NC_DISPATCH_VERSION for the dispatch table.

configure.ac

@@ -2064,12 +2064,12 @@ AX_SET_META([NC_HAS_SZIP],[$enable_hdf5_szip],[yes])
 AX_SET_META([NC_HAS_ZSTD],[$have_zstd],[yes])
 AX_SET_META([NC_HAS_BLOSC],[$have_blosc],[yes])
 AX_SET_META([NC_HAS_BZ2],[$have_bz2],[yes])
+
 # This is the version of the dispatch table. If the dispatch table is
 # changed, this should be incremented, so that user-defined format
 # applications like PIO can determine whether they have an appropriate
 # dispatch table to submit. If this is changed, make sure the value in
 # CMakeLists.txt also changes to match.
-
 AC_SUBST([NC_DISPATCH_VERSION], [5])
 AC_DEFINE_UNQUOTED([NC_DISPATCH_VERSION], [${NC_DISPATCH_VERSION}], [Dispatch table version.])
 

docs/dispatch.md

@@ -499,6 +499,31 @@ The code in *hdf4var.c* does an *nc_get_vara()* on the HDF4 SD
 dataset. This is all that is needed for all the nc_get_* functions to
 work.
 
+# Appendix A. Changing NC_DISPATCH_VERSION
+
+When new entries are added to the *struct NC_Dispatch* type
+-- located in *include/netcdf_dispatch.h.in -- it is necessary to
+do two things.
+1. Bump the NC_DISPATCH_VERSION number
+2. Modify the existing dispatch tables to include the new entries.
+It if often the case that the new entries do not mean anything for
+a given dispatch table. In that case, the new entries may be set to
+some variant of *NC_RO_XXX* or *NC_NOTNC4_XXX* *NC_NOTNC3_XXX*.
+
+Modifying the dispatch version requires two steps:
+1. Modify the version number in *netcdf-c/configure.ac*, and
+2. Modify the version number in *netcdf-c/CMakeLists.txt*.
+
+The two should agree in value.
+
+### NC_DISPATCH_VERSION Incompatibility
+
+When dynamically adding a dispatch table
+-- in nc_def_user_format (see libdispatch/dfile.c) --
+the version of the new table is compared with that of the built-in
+NC_DISPATCH_VERSION; if they differ, then an error is returned from
+that function.
+
 # Point of Contact {#dispatch_poc}
 
 *Author*: Dennis Heimbigner<br>