Merge pull request #1227 from billsacks/trim_changelog

Update ChangeLog template

cime_config/testdefs/testlist_clm.xml

@@ -2320,6 +2320,8 @@ for ERS test as otherwise it won't work for a sub-day test (no need to run this
         <options>
           <option name="wallclock">00:30:00</option>
           <option name="comment">Can use this test to determine if there are significant throughput changes, at least for this common and important configuration. Note that this deliberately doesn't have any testmods in order to (1) avoid doing history output (because the timing of output can be very variable, and mixing output timing with other aspects of model time can be confusing), and (2) generally keep the test replicating a production configuration as closely as possible (so, for example, we do NOT set BFBFLAG=TRUE for this test).</option>
+          <!-- standard throughput tolerance is 25%, but for this PFS test we want a stricter tolerance -->
+          <option name="tput_tolerance">0.1</option>
         </options>
       </machine>
     </machines>

doc/.ChangeLog_template

@@ -4,23 +4,12 @@ Originator(s):
 Date: 
 One-line Summary:
 
-Purpose of changes
-------------------
+Purpose and description of changes
+----------------------------------
 
 [Fill this in with details]
 
 
-Bugs fixed or introduced
-------------------------
-
-Issues fixed (include CTSM Issue #): [If none, remove this line]
-CIME Issues fixed (include issue #): [If none, remove this line]
-
-Known bugs introduced in this tag (include github issue ID): [If none, remove this line]
-
-Known bugs found since the previous tag (include github issue ID): [If none, remove this line]
-
-
 Significant changes to scientifically-supported configurations
 --------------------------------------------------------------
 
@@ -37,8 +26,23 @@ Does this tag change answers significantly for any of the following physics conf
 
 [ ] clm4_5
 
+
+Bugs fixed or introduced
+------------------------
+[Remove any lines that don't apply. Remove entire section if nothing applies.]
+
+Issues fixed (include CTSM Issue #):
+
+CIME Issues fixed (include issue #):
+
+Known bugs introduced in this tag (include issue #):
+
+Known bugs found since the previous tag (include issue #):
+
+
 Notes of particular relevance for users
 ---------------------------------------
+[Remove any lines that don't apply. Remove entire section if nothing applies.]
 
 Caveats for users (e.g., need to interpolate initial conditions):
 
@@ -48,53 +52,76 @@ Changes made to namelist defaults (e.g., changed parameter values):
 
 Changes to the datasets (e.g., parameter, surface or initial files):
 
-Substantial timing or memory changes: [For timing changes, can check PFS test(s) in the test suite]
+Substantial timing or memory changes:
+[For timing changes, you should at least check the PFS test in the test
+ suite, whether or not you expect timing changes: ensure that its run
+ time has not increased significantly relative to the baseline.]
 
-Notes of particular relevance for developers: (including Code reviews and testing)
+
+Notes of particular relevance for developers:
 ---------------------------------------------
 NOTE: Be sure to review the steps in README.CHECKLIST.master_tags as well as the coding style in the Developers Guide
+[Remove any lines that don't apply. Remove entire section if nothing applies.]
 
 Caveats for developers (e.g., code that is duplicated that requires double maintenance):
 
 Changes to tests or testing:
 
-CTSM testing:
 
-[... Remove before making master tag.  Available test levels:
+Testing summary:
+----------------
+[... Remove before making master tag.
+
+Nearly all CTSM tags should undergo 'regular' (aux_clm) testing.
+However, it occasionally makes sense to do more or less system testing;
+here is guidance on different available levels of system testing:
+    a) no system testing (for use when the only changes are ones that
+                          have absolutely no impact on system runs; this
+                          includes documentation-only tags, tags that
+                          just change the tools or some python code that
+                          does not impact system runs, etc.)
+    b) minimal (for use in rare cases where only a small change with 
+                known behavior is added ... eg. a minor bug fix. This
+		might be to just run the "short" test list, or to run
+		a single test. Whatever makes sense for the particular case.)
+    c) regular (regular tests on normal machines if CTSM source is modified)
+    d) release (regular tests plus the fates, ctsm_sci, mosart and rtm test lists
+                and normally all of the ancillary tests (build-namelist, python, ptclm, etc.) 
+		would be run as well)
+
+In addition, various other tests of the tools, python and perl
+infrastructure should be run when appropriate, as described below.
 
-    a) regular (must be run before handing off a tag to SEs and must be run
-     before committing a tag)
-    b) build_namelist (if namelists and/or build_system changed))
-    c) tools (only if tools are modified and no CTSM source is modified)
-    d) short (for use during development and in rare cases where only a small
-          change with known behavior is added ... eg. a minor bug fix)
-    e) doc (no source testing required)
+...]
 
-... ]
+[Remove any lines that don't apply.]
 
- [PASS means all tests PASS and OK means tests PASS other than expected fails.]
+ [PASS means all tests PASS; OK means tests PASS other than expected fails.]
 
-  build-namelist tests:
+  build-namelist tests (if CLMBuildNamelist.pm has changed):
 
     cheyenne - 
 
-  tools-tests (test/tools):
+  tools-tests (test/tools) (if tools have been changed):
 
     cheyenne - 
 
-  PTCLM testing (tools/shared/PTCLM/test):
+  PTCLM testing (tools/shared/PTCLM/test): (if cime or cime_config are changed)
+  (PTCLM is being deprecated, so we only expect this to be done on occasion)
 
     cheyenne - 
 
-  python testing (see instructions in python/README.md; document testing done):
+  python testing (if python code has changed; see instructions in python/README.md; document testing done):
 
     (any machine) - 
 
-  regular tests (aux_clm):
+  regular tests (aux_clm: https://github.com/ESCOMP/CTSM/wiki/System-Testing-Guide#pre-merge-system-testing):
 
     cheyenne ---- 
     izumi ------- 
 
+  any other testing (give details below):
+
 If the tag used for baseline comparisons was NOT the previous tag, note that here:
 
 
@@ -122,8 +149,9 @@ Changes answers relative to baseline:
    URL for LMWG diagnostics output used to validate new climate:
 
 
-Detailed list of changes
-------------------------
+Other details
+-------------
+[Remove any lines that don't apply. Remove entire section if nothing applies.]
 
 List any externals directories updated (cime, rtm, mosart, cism, fates, etc.):