docs: align spelling to US English and highlight config inheritance

rederik76 · rederik76 · commit c256013c8984 · 2026-07-13T12:14:31.000+10:00
Convert UK spellings across docs and ADRs to US forms and update the
spelling wordlist accordingly. Add a “Why teams use it” bullet on the
What is page for centralized framework configuration inheritance at runtime.
diff --git a/docs/decisions/0001-bundle-src-layout.md b/docs/decisions/0001-bundle-src-layout.md
@@ -13,7 +13,7 @@ modules and lifecycle scripts. This caused:
 
 - No separation between "code that gets installed on the cluster" and "code that spec
   references by module path".
-- No clear, fork-safe area for customer customisation.
+- No clear, fork-safe area for customer customization.
 - Ambiguity between `extensions/` (sys.path) and `extensions/libraries/` (a variant
   that was never released to `main`).
 
@@ -69,6 +69,6 @@ user-facing documentation to avoid confusion with callback-registration APIs.
   code. It is **not** required if libraries are sourced from PyPI, UC Volumes, or an
   artifact repository.
 - New bundles should place spec-referenced Python in `src/python/` and cluster-install
-  artefacts in `src/libraries/` (if bundled).
+  artifacts in `src/libraries/` (if bundled).
 - The `pipeline_bundle_template/` and samples are migrated to this layout in this PR.
 - Existing bundles using `extensions/` continue to work until `v1.0.0` (see ADR-0002).
diff --git a/docs/decisions/0002-extensions-deprecation.md b/docs/decisions/0002-extensions-deprecation.md
@@ -22,12 +22,12 @@ The new canonical path (`src/python/`) was introduced in ADR-0001.
 
 ## Decision
 
-| Legacy behaviour | Released? | Action in v0.13.0 | Removed in |
+| Legacy behavior | Released? | Action in v0.13.0 | Removed in |
 |-----------------|-----------|-----------------|------------|
 | Flat `extensions/` on `sys.path` | Yes | Emit `DeprecationWarning` + structured log | **v1.0.0** |
 | `extensions/libraries/` on `sys.path` | No | Drop immediately, no deprecation window | **v0.13.0** (this PR) |
 
-**One-minor deprecation window:** deprecated behaviour is removed in the first minor
+**One-minor deprecation window:** deprecated behavior is removed in the first minor
 version after the deprecation warning lands — giving consumers one release cycle to
 migrate before the path disappears.
 
diff --git a/docs/decisions/0004-mirror-to-stdout-default.md b/docs/decisions/0004-mirror-to-stdout-default.md
@@ -62,7 +62,7 @@ default logger is returned unchanged.
 - The `lakeflowframework` `logging.Logger` instance is modified in-place when
   silenced. Any code that obtained a direct `logging.getLogger("lakeflowframework")`
   reference before logger resolution will stop producing output — this is the
-  intended behaviour.
+  intended behavior.
 - `mirror_to_stdout: false` is the breaking change relative to the previous
   hard-coded stdout logger. Teams relying on plain-text stdout output and also
   enabling a custom logger must set `mirror_to_stdout: true` explicitly.
diff --git a/docs/decisions/0005-syspath-registration-decoupled-from-logger.md b/docs/decisions/0005-syspath-registration-decoupled-from-logger.md
@@ -1,4 +1,4 @@
-# ADR-0005: `sys.path` registration decoupled from logger initialisation
+# ADR-0005: `sys.path` registration decoupled from logger initialization
 
 **Date:** 2026-05-17
 **Status:** Accepted
diff --git a/docs/decisions/0006-local-config-sparse-overlay.md b/docs/decisions/0006-local-config-sparse-overlay.md
@@ -30,7 +30,7 @@ The original framework config mechanism offered a binary choice: use
    resolution like `GLOBAL_CONFIG`).
 
 The `src/local/` fork-safe area introduced in ADR-0001 provides a natural home
-for customer customisations. Config overrides should follow the same pattern.
+for customer customizations. Config overrides should follow the same pattern.
 
 ## Decision
 
@@ -47,7 +47,7 @@ Override detection and deprecation warnings are the **caller's responsibility**.
   active, stores the resolved root in `self._active_config_path`, and passes it
   to `load_framework_config`.  `self._active_config_path` is reused by
   `_setup_operational_metadata` so the override detection only runs once per
-  pipeline initialisation.
+  pipeline initialization.
 
 - **`load_framework_logger_config`** independently checks
   `config/override/logger.json`, emits its own `DeprecationWarning` if active,
@@ -66,7 +66,7 @@ load_framework_config(
 ) -> Dict
 ```
 
-Behaviour:
+Behavior:
 
 1. When `name` is a **sequence** (e.g. `FrameworkPaths.GLOBAL_CONFIG =
    ("global.json", "global.yaml", "global.yml")`):
diff --git a/docs/decisions/0008-lakeflow-framework-package.md b/docs/decisions/0008-lakeflow-framework-package.md
@@ -137,7 +137,7 @@ module is added.
   risk with customer code.
 - Existing flat-deploy customers are unaffected: the `src/` shims preserve
   backward compatibility, and `framework.sourcePath` + Workspace Files-first
-  resolution (ADR-0009) means behaviour is identical to pre-v0.20.0.
+  resolution (ADR-0009) means behavior is identical to pre-v0.20.0.
 - Editable installs (`pip install -e ".[contrib]"`) are supported for local
   development; the `src/` layout ensures the installed package and the source
   tree are the same directory.
diff --git a/docs/decisions/0009-strategy-b-workspace-files-first-resolver.md b/docs/decisions/0009-strategy-b-workspace-files-first-resolver.md
@@ -32,7 +32,7 @@ first when both a Workspace Files path and the wheel package data are potentiall
 - `+` Simple: the wheel is always the canonical source of defaults.
 - `−` **Breaking for existing flat-deploy customers.** Their defaults live in
   Workspace Files; if the wheel shadow-contains a newer (or different) version of a default
-  file, behaviour silently changes on upgrade.
+  file, behavior silently changes on upgrade.
 - `−` Contradicts the "explicit wins" principle: a customer who set
   `framework.sourcePath` explicitly expects Workspace Files to be authoritative.
 
@@ -91,7 +91,7 @@ similar validators.
 
 - **Zero-change upgrade for flat-deploy customers.** Their `framework.sourcePath`
   points to the deployed `src/` directory in Workspace Files; those files are
-  found at step 1 and the wheel is never consulted. Behaviour is identical to
+  found at step 1 and the wheel is never consulted. Behavior is identical to
   pre-v0.20.0.
 - **Explicit wins.** Setting `framework.sourcePath` is a deliberate act.
   Workspace Files-first honours that intent; package-first would silently override it.
@@ -108,7 +108,7 @@ similar validators.
   config and schema reads; call sites that previously used
   `os.path.join(framework_path, FrameworkPaths.CONFIG_PATH, name)` are
   migrated to it.
-- Flat-deploy customers see **no behaviour change** on upgrade to v0.20.0.
+- Flat-deploy customers see **no behavior change** on upgrade to v0.20.0.
 - Wheel-install customers get defaults from the wheel with no `framework.sourcePath`
   required.
 - The `src/local/config/` sparse overlay (ADR-0006) continues to work in all
diff --git a/docs/source/architecture/index.rst b/docs/source/architecture/index.rst
@@ -14,10 +14,10 @@ The Lakeflow Framework is designed to support different organizational and data
 * Federated domain-aligned teams, including data mesh and data product approaches
 * Hybrid operating models that combine centralized governance with domain ownership
 
-**Modelling paradigms**
+**Modeling paradigms**
 
 * Medallion architecture (Bronze, Silver, Gold)
-* Common modelling patterns, including dimensional (facts/dimensions), Data Vault, enterprise canonical/3NF, and other custom enterprise models
+* Common modeling patterns, including dimensional (facts/dimensions), Data Vault, enterprise canonical/3NF, and other custom enterprise models
 
 These approaches can be implemented using the same Data Flow Spec-driven patterns, deployment process, and framework features documented in this guide.
 
diff --git a/docs/source/build/bundle-steps.rst b/docs/source/build/bundle-steps.rst
@@ -277,7 +277,7 @@ See :doc:`/features/data-quality/expectations`.
 
 **Add pipeline logic modules** *(optional)* — if the spec references custom Python
 (``pythonModule``, ``pythonTransform.module``, or a custom sink), add modules or packages under ``src/python/``.
-The framework adds ``src/python/`` to ``sys.path`` at pipeline initialisation.
+The framework adds ``src/python/`` to ``sys.path`` at pipeline initialization.
 See :doc:`/features/python/extensions`.
 
 .. note::
diff --git a/docs/source/build/bundle-structure.rst b/docs/source/build/bundle-structure.rst
@@ -69,7 +69,7 @@ The high-level structure of a Pipeline Bundle never changes and is as follows:
     │   ├── init/
     │   │   ├── pre/                 # Lifecycle scripts — run before SDP declarations (optional)
     │   │   └── post/                # Lifecycle scripts — run after SDP declarations (optional)
-    │   ├── libraries/               # Cluster-install artefacts + sys.path loose .py (optional)
+    │   ├── libraries/               # Cluster-install artifacts + sys.path loose .py (optional)
     │   ├── pipeline_configs/        # Global and env-specific pipeline config (required)
     │   └── python/                  # Spec-referenced Python modules and packages (optional)
     ├── databricks.yml
@@ -89,7 +89,7 @@ The ``src/`` directories serve distinct purposes:
      - Purpose
    * - ``src/dataflows/``
      - All Data Flow Spec files. The framework reads every spec file recursively regardless
-       of sub-folder structure. See below for organisation options.
+       of sub-folder structure. See below for organization options.
    * - ``src/init/pre/`` and ``src/init/post/``
      - **Optional.** Lifecycle ``.py`` scripts executed before and after SDP declarations
        inside ``initialize_pipeline()``. Run in sorted filename order; files starting
@@ -106,15 +106,15 @@ The ``src/`` directories serve distinct purposes:
    * - ``src/python/``
      - **Optional.** All customer Python referenced by Data Flow Specs —
        ``pythonModule``, ``pythonTransform.module``, and custom sinks. Added to
-       ``sys.path`` at pipeline initialisation.
+       ``sys.path`` at pipeline initialization.
 
 .. seealso::
 
    :doc:`/features/python/extensions` — full reference for ``src/libraries/``,
    ``src/python/``, ``src/init/``, and ``src/local/config/``, including examples,
    deprecation notices, and the cluster library installation options.
 
-It is the structure of the ``src/dataflows`` directory that is flexible and can be organised in the way that best suits your standards and ways of working. The Framework will:
+It is the structure of the ``src/dataflows`` directory that is flexible and can be organized in the way that best suits your standards and ways of working. The Framework will:
 
 * Read all the Data Flow Spec files under the ``src/dataflows`` directory, regardless of the folder structure. Filtering of the data flows is done when defining your Pipeline and is discussed in the :doc:`/build/bundle-steps` section.
 * Expect that the schemas, transforms and expectations related to a Data Flow Spec are located in their respective ``schemas``, ``dml`` and ``expectations`` sub-directories within the Data Flow Spec's home directory.
diff --git a/docs/source/build/patterns/basic-1-1.rst b/docs/source/build/patterns/basic-1-1.rst
@@ -19,7 +19,7 @@ Use when:
 
 - You are ingesting data or performing one-to-one loads.
 - You are promoting one upstream table into a conformed entity table.
-- You need append-only, SCD1, or SCD2 behaviour on the target.
+- You need append-only, SCD1, or SCD2 behavior on the target.
 - You only need basic single-row transforms (data type conversion, formatting, cleansing, data quality).
 
 **Layers:** Bronze and Silver
diff --git a/docs/source/build/patterns/index.rst b/docs/source/build/patterns/index.rst
@@ -7,22 +7,22 @@ Reference patterns for designing data flows and pipelines.
 
 Start with :doc:`Base Patterns </build/patterns/base-patterns>` (bronze → silver → gold), then adopt :doc:`Advanced composition </build/patterns/advanced-composition>` patterns when sources, keys, or join semantics require them.
 
-* Operating models and modelling paradigms: :doc:`/architecture/index`
+* Operating models and modeling paradigms: :doc:`/architecture/index`
 * :doc:`/features/platform/multi-source-streaming`
 * :doc:`/build/bundle-structure`
 * :doc:`/build/patterns/scaling-decomposing-pipelines`
 * :doc:`/build/patterns/mix-and-match-patterns`
 * SDP concepts (datasets, flows): `Lakeflow Spark Declarative Pipelines — key concepts <https://docs.databricks.com/aws/en/ldp/concepts/#key-concepts>`_
 
-When selecting a pattern, start with ownership model, modelling approach, source characteristics (streaming, static, CDC), and latency needs.
+When selecting a pattern, start with ownership model, modeling approach, source characteristics (streaming, static, CDC), and latency needs.
 
 .. note::
 
-   These patterns are **not an exhaustive catalog** of everything the Lakeflow Framework supports. They are a curated **starting point** — common building blocks and composition approaches that align with the bundled ``pattern-samples`` and what most teams implement first. Combine, extend, or depart from them as your sources, modelling, and operational constraints require.
+   These patterns are **not an exhaustive catalog** of everything the Lakeflow Framework supports. They are a curated **starting point** — common building blocks and composition approaches that align with the bundled ``pattern-samples`` and what most teams implement first. Combine, extend, or depart from them as your sources, modeling, and operational constraints require.
 
 .. tip::
 
-   **Runnable samples:** End-to-end specs live in ``samples/pattern-samples`` (bronze → silver → gold, multi-source streaming, stream-static joins, CDC from snapshot, gold materialized views, and more). See :doc:`/samples/index` for deploy steps. Each pattern page links to the matching specs in that bundle; advanced pattern pages also include multi-day example data flows for SCD and late-arriving behaviour.
+   **Runnable samples:** End-to-end specs live in ``samples/pattern-samples`` (bronze → silver → gold, multi-source streaming, stream-static joins, CDC from snapshot, gold materialized views, and more). See :doc:`/samples/index` for deploy steps. Each pattern page links to the matching specs in that bundle; advanced pattern pages also include multi-day example data flows for SCD and late-arriving behavior.
 
 .. rubric:: Base Patterns
 
diff --git a/docs/source/build/patterns/multi-source-streaming.rst b/docs/source/build/patterns/multi-source-streaming.rst
@@ -131,7 +131,7 @@ Example Data Flow
 
 .. note::
 
-   In the below example data flow, customer ID 4 demonstrates the behaviour for late arriving records in streaming sources. This ultimately means you will potentially have more versions for a row in SCD2 scenarios. This needs to be weighed against your requirements and will either be acceptable or not. If this is not acceptable, please refer to the stream-static patterns below.
+   In the below example data flow, customer ID 4 demonstrates the behavior for late arriving records in streaming sources. This ultimately means you will potentially have more versions for a row in SCD2 scenarios. This needs to be weighed against your requirements and will either be acceptable or not. If this is not acceptable, please refer to the stream-static patterns below.
 
 Day 1 Load
 ~~~~~~~~~~
diff --git a/docs/source/build/spec-reference/materialized-views.rst b/docs/source/build/spec-reference/materialized-views.rst
@@ -230,7 +230,7 @@ These properties define the source of the data:
      - **Description**
    * - **sourceSystem** (*optional*)
      - ``string``
-     - The source system name. Value is not used to determine or change any behaviour.
+     - The source system name. Value is not used to determine or change any behavior.
    * - **sourceType**
      - ``string``
      - The type of source.  
diff --git a/docs/source/build/spec-reference/standard.rst b/docs/source/build/spec-reference/standard.rst
@@ -151,7 +151,7 @@ These properties define the source of the data:
      - **Description**
    * - **sourceSystem** (*optional*)
      - ``string``
-     - The source system name. Value is not used to determine or change any behaviour, required if `dataFlowType` is `standard`.
+     - The source system name. Value is not used to determine or change any behavior, required if `dataFlowType` is `standard`.
    * - **sourceType**
      - ``string``
      - The type of source, required if `dataFlowType` is `standard`.  
diff --git a/docs/source/deploy/framework/options.rst b/docs/source/deploy/framework/options.rst
@@ -30,7 +30,7 @@ configuration.
        ``src/local/config/`` sparse overrides are deep-merged on top of the
        bundled defaults.
      - Teams that want pip-managed installs but need per-deployment config
-       customisation.
+       customization.
 
 .. note::
    For wheel based deployments it is your responsibility to provide
diff --git a/docs/source/deploy/framework/wheel.rst b/docs/source/deploy/framework/wheel.rst
@@ -91,7 +91,7 @@ Backward compatibility
 
 - **Existing flat-deploy customers** are unaffected.  The workspace files first
   resolution means that if ``framework.sourcePath`` is set and default files
-  are in workspace files, they take priority over the wheel — behaviour is identical to
+  are in workspace files, they take priority over the wheel — behavior is identical to
   earlier releases.
 - **Compat shims** at the old flat ``src/`` import paths (e.g.
   ``from constants import FrameworkPaths``) remain until v1.0.0.  Prefer
diff --git a/docs/source/features/configuration/logging.rst b/docs/source/features/configuration/logging.rst
@@ -258,7 +258,7 @@ Example — framework-level structured stdout logger (``src/local/``)
    :doc:`/features/python/extensions`. That approach decouples the logger from
    the framework bundle and lets it be versioned and distributed independently.
    Using ``src/local/libraries/`` is best suited for lightweight, org-specific
-   customisations that you want to keep co-located with the framework bundle.
+   customizations that you want to keep co-located with the framework bundle.
 
 The following walkthrough sets up a structured JSON stdout logger at the
 framework level using ``src/local/libraries/``. Each log record is emitted as
@@ -481,7 +481,7 @@ Troubleshooting
 Custom logger not loading / pipeline still uses default logger
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The framework always falls back to the default stdout logger on any initialisation
+The framework always falls back to the default stdout logger on any initialization
 error rather than failing the pipeline. Check the pipeline logs for a warning
 beginning with ``Failed to initialize custom logger:`` — the message will contain
 the original exception.
@@ -524,7 +524,7 @@ add a thin wrapper (see below) that maps the argument:
 Third-party logger cannot be called as ``factory(dbutils, spark, **factory_args)``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Some loggers require multi-step initialisation, a context manager, or arguments
+Some loggers require multi-step initialization, a context manager, or arguments
 that are incompatible with the framework's injection. Place a thin wrapper in
 ``src/local/libraries/`` (framework bundle) or as a cluster-installed module
 (pipeline bundle). The wrapper's ``get_logger`` handles the adaptation and
diff --git a/docs/source/features/metadata/schema-management.rst b/docs/source/features/metadata/schema-management.rst
@@ -46,7 +46,7 @@ Schema Types
 Schema File Location
 --------------------
 
-Schema definitions must be specified in their own dedicated files and will be located in a schemas folder, dependant on your chosen bundle structure as discussed in the :doc:`/build/bundle-structure` section.
+Schema definitions must be specified in their own dedicated files and will be located in a schemas folder, dependent on your chosen bundle structure as discussed in the :doc:`/build/bundle-structure` section.
 
 Data Flow Spec Configuration
 ----------------------------
diff --git a/docs/source/features/metadata/spec-format.rst b/docs/source/features/metadata/spec-format.rst
@@ -227,7 +227,7 @@ The following example shows a data flow specification in both JSON and YAML form
 Best Practices
 --------------
 
-1. **Choose One Format Globally**: While technically possible to mix formats across Bundles, it's recommended to standardise on a single format.
+1. **Choose One Format Globally**: While technically possible to mix formats across Bundles, it's recommended to standardize on a single format.
 
 2. **Version Control Considerations**: YAML may produce cleaner diffs in version control systems due to its more human-readable format and lack of trailing commas.
 
diff --git a/docs/source/features/metadata/validation.rst b/docs/source/features/metadata/validation.rst
@@ -140,7 +140,7 @@ If you are using GitHub Actions for your CI/CD pipelines, you can use the **comp
              # no-mapping: 'false'
              # verbose: 'false'
 
-The ``uses`` line can reference the ``databricks-solutions/lakeflow_framework`` (upstream) or **your organisation's fork/clone** of the Lakeflow Framework repository. The path ``.github/actions/validate-dataflows`` is the same; set the owner and pin ``@<ref>`` to a tag or commit that exists on whichever repository you rely on.
+The ``uses`` line can reference the ``databricks-solutions/lakeflow_framework`` (upstream) or **your organization's fork/clone** of the Lakeflow Framework repository. The path ``.github/actions/validate-dataflows`` is the same; set the owner and pin ``@<ref>`` to a tag or commit that exists on whichever repository you rely on.
 
 Pin to a tag or a commit instead of a moving branch for reproducible CI (e.g., replace @main with @v0.11.0).
 
diff --git a/docs/source/features/python/extensions.rst b/docs/source/features/python/extensions.rst
diff --git a/docs/source/features/python/functions.rst b/docs/source/features/python/functions.rst
diff --git a/docs/source/features/python/source.rst b/docs/source/features/python/source.rst
diff --git a/docs/source/get-started/what-is-lakeflow-framework.rst b/docs/source/get-started/what-is-lakeflow-framework.rst
diff --git a/docs/source/spelling_wordlist.txt b/docs/source/spelling_wordlist.txt
diff --git a/samples/README.md b/samples/README.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# ADR-0005: `sys.path` registration decoupled from logger initialisation
	`1`	+# ADR-0005: `sys.path` registration decoupled from logger initialization
`2`	`2`
`3`	`3`	`Date: 2026-05-17`
`4`	`4`	`Status: Accepted`