upgrade/v2212-User-Upgrade-Guide.md

@@ -4,20 +4,93 @@
 [![upgrade](/icons/chevrons-up.svg "upgrade guide")][upgrade-guide]
 [![code](/icons/code.svg "coding patterns")][code-patterns]
 
-***Preview information, subject to change at any time !!!***
-
 [[_TOC_]]
 
-## Deprecation and Removal
+## Changes in behaviour
 
-### Deprecated Models
+### timeActivatedFileUpdate
 
-## Rename
+For `timeActivatedFileUpdate`, missing files are now treated as a
+critical error (FatalIOError). These were previously treated as a
+simple error (FatalError), which downgrades to a Warning only when
+loading a functionObject and meant that configuration errors would not
+be noticed.
 
-## Configuration / Environment
 
 ## Input Dictionaries
 
+### Force, Force coefficients
+
+More consistent handling of priorities for binModels, forces.
+If the dictionaries are overspecified, give a `coordinateSystem`
+entry a higher prioriy than the `CofR` shortcuts.
+
+
+### Streamline Improvements
+
+Some of the streamline handling has been further refined
+(eg, barycentric coordinates in interpolation instead of x/y/z).
+In the process the input requirements has been relaxed:
+
+- default tracking direction is 'forward'
+- The `U` (velocity) field doesn't need to be named in the sampled
+  fields.
+
+
+### Improved handling of coordinateSystems
+
+Wherever the coordinate system definition is embedded within a
+sub-dictionary scope the `origin` keyword is now optional. For
+example,
+```
+dict1
+{
+    coordinateSystem
+    {
+        origin (0 0 0);  // now optional here
+        rotation ...;
+    }
+}
+```
+However, it remains mandatory if constructed without a sub-dict. For
+example,
+```
+dict2
+{
+    origin (0 0 0);   // still mandatory
+    e1  (1 0 0);
+    e3  (0 0 1);
+}
+```
+With this change, the _transform_ sub-dictionary can be written more
+naturally:
+```
+formatOptions
+{
+   vtk
+   {
+       scale 1000;  // m -> mm
+       transform
+       {
+           rotationCentre  (1 0 0);
+           rotation axisAngle;
+           axis    (0 0 1);
+           angle   -45;
+       }
+   }
+}
+```
+
+
+## Changes in utilities
+
+### Updated option names for `transformPoints` and `surfaceTransformPoints`
+
+New options `-auto-centre` and `-centre` replace `-auto-origin` and
+`-origin`, respectively (old options still accepted as compatibility
+aliases). Changing to `-centre` avoids possible confusion in meaning
+with coordinate system `origin()`.
+
 
 ----