upgrade/v2106-Developer-Upgrade-Guide.md

@@ -8,20 +8,135 @@
 
 [[_TOC_]]
 
+## Incompatibilities
+
+- `fvMeshDistribute` : geometric tolerances have been removed, which
+  means that the constructor now takes a single parameter only.
+
+- _protected_ `UList::size(label)` : renamed to `setAddressableSize(label)`
+  <br>
+  The longer name for this low-level _protected_ method eliminates
+  some ambiguity (eg, with `resize`, `setSize`) and enables more
+  precise inheritance patterns. The name is consistent with
+  PtrListDetail internals.
+
+- `ITstream` : parsing constructor
+  <br>
+  Elminate mandatory name for parsing versions. This makes it easier
+  to use ITstream, IStringStream, UListStream interchangeable.
+
+
 ## Deprecation and Removal
 
 ### Deprecated Methods
 
+Internal hashing functors have been standardized with method name to
+reduce clutter and provide better alignment with standard C++ practices.
+
+```
+// Old:
+FixedList<label, 3>::Hash<>()
+
+// New:
+FixedList<label, 3>::hasher()
+
+// Unchanged:
+labelHashSet::hasher()
+```
+Existing `Hash<>` functor namings are still supported, but deprecated.
+
+
 ### Removed Methods
 
+- The `longestEdge` global function, which was deprecated and replaced by the
+`face::longestEdge()` method (2017-04) has now been removed.
+
+- Removed construct List from two iterators. This constructor was
+  added for similarity with std::vector, but continues to cause
+  various annoyances. If The `ListOps::create()` function provides a
+  lengthier alternative but one that can also incorporate
+  transformations.
+
+- removed `fileName::clean() const` method<br>
+  Relying on const/non-const to control the behaviour (inplace change
+  or return a copy) is too fragile and the const version was almost
+  never used. Now replace with a two-stage process when needed.
+  ```
+  // OLD (2012 and earlier)
+  fileName sanitized = constPath.clean();
+
+  // NEW (2106)
+  fileName sanitized(constPath);
+  sanitized.clean());
+  ```
+
 ### Removed Items
 
 ## Changes in definition
 
+
 ## Changes in behaviour
 
-## Namespace changes
+- construction of `DynamicField` with a size is now consistent with
+  `DynamicList` - it now reserves space only and leaves the initial
+  addressable size as zero.
+
+
+## Tokenization/Parsing Improvements
+
+To better harness the OpenFOAM parsing routines, the token handling
+and ITstream have been extended to include numerous _failsafe_ access
+methods and direct checking of types.
+
+Direct check of punctuation and word tokens: For example,
+```
+if (tok.isWord("uniform")) ..
+
+while (!tok.isPunctuation(token::BEGIN_LIST)) ..
+```
+instead of the equivalent lengthier versions:
+```
+if (tok.isWord() && tok.wordToken() == "uniform") ..
+
+while (!(tok.isPunctuation() && tok.pToken() == token::BEGIN_LIST)) ..
+```
+
+
+Failsafe versions for lookahead tokens: Istream peek(), ITstream
+peek(), peekFirst(), peekLast(). Failsafe traversing: ITstream skip().
+This makes it possible to write LALR(1) parsers using OpenFOAM
+classes.
+
+For example,
+```
+ITstream& is = dict.lookup(key);
+if (is.peek().isWord())
+{
+    is.skip();
+}
+```
+
+
+## New methods
+
+The `face` class now has a symmetric hasher that starts with lowest
+vertex value and walks in the direction of the next lowest value. This
+ensures that the hash code is independent of face orientation and face
+rotation.
+
+
+## Other
+
+- Replaced keyType with wordRe for matching selections
+
+- noexcept version of size_bytes() for List and other containers.
+  Used when the is_contiguous check has already been done outside
+  the loop. Naming as per std::span.
+
+
+----
 
 [code-patterns]: /coding/patterns/patterns
+[upgrade-guide]: /upgrade/upgrade
 
 [v2106-notes]: https://www.openfoam.com/releases/openfoam-v2106/