add note about PR 173 and clarification for hint precedence

Author: wkliao

sneak_peek.md

@@ -90,6 +90,47 @@ This is essentially a placeholder for the next release note ...
 * Issues related to Darshan library:
   + none
 
-* Clarifications
-  + none
+* Clarifications about of PnetCDF hints
+  + There are three ways in PnetCDF for user to set hints to align the starting
+    file offset for the data section (header extent) and record variable
+    section.
+    1. through a call to API `nc_header_align_size` by setting arguments of
+       `h_minfree`, `v_align`, `v_minfree`, and `r_align`.
+    2. through an MPI info object passed to calls of `ncmpi_create()` and
+       `ncmpi_open()`. Hints are `nc_header_align_size`, `nc_var_align_size`,
+       and `nc_record_align_size`.
+    3. through a run-time environment variable `PNETCDF_HINTS`. Hints are
+       `nc_header_align_size`, `nc_var_align_size`, and `nc_record_align_size`.
+  + As the same hints may be set by one or more of the above methods, PnetCDF
+    implements the following hint precedence.
+    * `PNETCDF_HINTS` > `ncmpi__enddef()` > `MPI info`.
+    * 1st priority: hints set in the environment variable `PNETCDF_HINTS`, e.g.
+      `PNETCDF_HINTS="nc_var_align_size=1048576"`. Making this the first
+      priority is because it allows to run the same application executable
+      without source code modification using different alignment settings
+      through a run-time environment variable.
+    * 2nd priority: hints set in the MPI info object passed to calls of
+      `ncmpi_create()` and `ncmpi_open()`, e.g.
+      `MPI_Info_set("nc_var_align_size", "1048576");`. The reasoning is when a
+      3rd-party library built on top of PnetCDF implements its codes using
+      'ncmpi__enddef'. An application that uses such 3rd-party library can pass
+      an MPI info object to it, which further passes the info to PnetCDF. This
+      precedence allows that application to exercise different hints without
+      changing the 3rd-party library's source codes.
+    * 3rd priority: hints used in the arguments of `ncmpi__enddef()`, e.g.
+      `ncmpi__enddef(..., v_align=1048576,...)`.
+  + PnetCDF I/O hint `nc_header_align_size` is essentially the same as hint
+    `nc_var_align_size`, but its name appears to be closer to the hint's
+    intent, i.e. to reserve some space for the header growth in the future when
+    new data objects are added. Please note when both hints are set, only hint
+    `nc_var_align_size` will take effect and `nc_header_align_size` ignored.
+  + When there is no fix-sized variable (i.e. non-record variable) defined,
+    argument `v_minfree` passed to `ncmpi__enddef()` is ignored. In this
+    case, users should set `h_minfree`, if an extra header space is desired.
+  + When there is no fix-sized variables defined and none of hints
+    `nc_header_align_size`, `nc_var_align_size`, or argument `v_align` is set,
+    `nc_record_align_size` or `r_align`, if set, will be used to align the
+    header extent.
+  + For the above update to the hint precedence, see
+    PnetCDF See [PR #173](https://github.com/Parallel-NetCDF/PnetCDF/pull/173).