📝 Updates to config & defaults processing order

docs/BreakingChanges.md

@@ -7,7 +7,7 @@ These breaking changes are complemented by two other documents:
 
 ---
 
-# [1.0.0 pre-release] — 2024-04-02
+# [1.0.0 pre-release] — 2024-06-19
 
 ## Explicit `:paths` ↳ `:include` entries in the project file
 
@@ -75,6 +75,12 @@ Each test is now treated as its own mini-project. Differentiating components of
 
 Release build object files were previously segregated by their source. The release build output directory had subdirectories `c/` and `asm/`. These subdirectories are no longer in use.
 
+## Configuration defaults and configuration set up order
+
+Ceedling’s previous handling of defaults and configuration processing order certainly worked, but it was not as proper as it could be. To oversimplify, default values were applied in an ordering that caused complications for advanced plugins and advanced users. This has been rectified. Default settings are now processed after all user configurations and plugins.
+
+For some users and some custom plugins, the new ordering may cause unexpected results. The changes had no known impact on existing plugins and typical project configurations.
+
 ## Changes to global constants & accessors
 
 Some global constant “collections” that were previously key elements of Ceedling have changed or gone away as the build pipeline is now able to process a configuration for each individual test executable in favor of for the entire suite.

docs/CeedlingPacket.md

@@ -1697,7 +1697,7 @@ YAML.
 
 The next section details Ceedling’s project configuration options in 
 YAML. This section explains all your options for loading and modifying 
-project configuration from files to begin with.
+project configuration.
 
 ## Overview of Project Configuration Loading & Smooshing
 
@@ -1707,13 +1707,17 @@ this:
 
 1. Load the base project configuration from a YAML file.
 1. Merge the base configuration with zero or more Mixins from YAML files.
-1. Load zero or more plugins that alter or merge additional configuration.
-1. Merge in default values to ensure all necessary configuration to run
-   is present.
+1. Load zero or more plugins that provide default configuration values
+   or alter the base project configuration.
+1. Populate the configuration with default values to ensure all necessary 
+   configuration to run is present.
 
 Ceedling provides reasonably verbose logging at startup telling you which
 configuration files were used and in what order they were merged.
 
+For nitty-gritty details on plugin configuration behavior, see the
+_[Plugin Development Guide](PluginDevelopmentGuide.md)_
+
 ## Options for Loading Your Base Project Configuration
 
 You have three options for telling Ceedling what single base project 

docs/Changelog.md

@@ -9,7 +9,7 @@ This changelog is complemented by two other documents:
 
 ---
 
-# [1.0.0 pre-release] — 2024-06-12
+# [1.0.0 pre-release] — 2024-06-19
 
 ## 🌟 Added
 
@@ -191,6 +191,10 @@ The environment variable option for pointing Ceedling to a project file other th
 
 Documentation on Mixins and the new options for loading a project configuration are thoroughly documented in _[CeedlingPacket](CeedlingPacket.md))_.
 
+### Configuration defaults and configuration set up order
+
+Ceedling’s previous handling of defaults and configuration processing order certainly worked, but it was not as proper as it could be. To oversimplify, default values were applied in an ordering that caused complications for advanced plugins and advanced users. This has been rectified. Default settings are now processed after all user configurations and plugins.
+
 ### Plugin system improvements
 
 1. The plugin subsystem has incorporated logging to trace plugin activities at high verbosity levels.

docs/PluginDevelopmentGuide.md

@@ -111,7 +111,7 @@ programmatic `Plugin` subclasses (Ceedling plugins options #2).
    that Ceedling incorporates into its configuration defaults during startup. 
    This provides the greatest flexibility in creating configuration values.
 1. **YAML configurations.** The data of a simple YAML file is incorporated into
-   Ceedling's configuration much like Ceedling's actual configuration file.
+   Ceedling's configuration much like your project configuration file.
 
 ## Example configuration plugin layout
 
@@ -141,21 +141,39 @@ project/
 
 ## Ceedling configuration build & use
 
-Configuration is developed at startup in this order:
+Configuration is developed at startup by assembling defaults, collecting 
+user-configured settings, and then populating any missing values with defaults.
 
-1. Ceedling loads its own defaults
-1. Any plugin defaults are inserted, if they do not already exist
-1. Any plugin configuration is merged
-1. Project file configuration is merged
+Defaults:
 
-Merging means that any existing configuration is replaced. If no such 
-key/value pairs already exist, they are inserted into the configuration.
+1. Ceedling loads its own defaults separately from your project configuration
+1. Supporting framework defaults such as for CMock are populated into (1)
+1. Any plugin defaults are merged with (2).
 
-A plugin may further implement its own code to use custom configuration added to
-the Ceedling project file. In such cases, it's typically wise to make use of a
-plugin's option for defining default values. Configuration handling code is
-greatly simplified if strucures and values are guaranteed to exist in some
-form.
+Final project configuration:
+
+1. Your project file is loaded and any mixins merged
+1. Supporting framework settings that depend on project configuration are populated
+1. Plugin configurations are merged with the result of (1) and (2)
+1. Defaults are populated into your project configuration
+1. Path standardization, string replacement, and related occur throughout the final 
+   configuration
+
+Merging means that existing simple configuration valuees are replaced or, in the 
+case of containers such as lists and hashes, values are added to. If no such 
+key/value pairs already exist, they are simply inserted into the configuration. 
+
+Populating means inserting a configuration value if none already exists. As an 
+example, if Ceedling finds no compiler defined for test builds in your project
+configuration, it populates your configuration with its own internal tool definition.
+
+A plugin may implement its own code to use extract custom configuration from
+the Ceedling project file. See the built-in plugins for examples. For instance, the
+Beep plugin makes use of a top-level `:beep` section in project configuration. In 
+such cases, it's typically wise to make use of a plugin's option for defining 
+default values. Configuration handling code is greatly simplified if values are 
+guaranteed to exist in some form. This elimiates a great deal of presence checking
+and related code.
 
 ## Configuration Plugin Flavors
 

docs/ReleaseNotes.md

@@ -7,7 +7,7 @@ These release notes are complemented by two other documents:
 
 ---
 
-# 1.0.0 pre-release — June 12, 2024
+# 1.0.0 pre-release — June 19, 2024
 
 ## 🏴‍☠️ Avast, Breaking Changes, Ye Scallywags!
 
@@ -159,6 +159,10 @@ The `:simple` and `:gdb` options for this feature fully and correctly report eac
 
 See _[CeedlingPacket](CeedlingPacket.md))_ for the new `:project` ↳ `:use_backtrace` feature to control how much detail is extracted from a crashed test executable to help you find the cause.
 
+#### Configuration defaults and configuration set up order
+
+Ceedling’s previous handling of defaults and configuration processing order certainly worked, but it was not as proper as it could be. To oversimplify, default values were applied in an ordering that caused complications for advanced plugins and advanced users. This has been rectified. Default settings are now processed after all user configurations and plugins.
+
 #### Documentation
 
 The Ceedling user guide, _[CeedlingPacket](CeedlingPacket.md)_, has been significantly revised and expanded. We will expand it further in future releases and eventually break it up into multiple documents or migrate it to a full documentation management system.