From 9babe8afdb1a7c4408d1d98ec73f618926eee5dd Mon Sep 17 00:00:00 2001
From: Scott Draper <admin@scottdraper.io>
Date: Sat, 14 Mar 2026 11:29:26 -0600
Subject: [PATCH 1/2] Clarify id_field and parent_field semantics in docs

---
 docs/configuration.md | 25 ++++++++++++++++++++++---
 docs/ids.md           | 14 ++++++++++++--
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index d88ff9f..7374129 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -115,15 +115,34 @@ These parameters have sensible defaults and rarely need adjustment.
 **Type:** `str`
 **Default:** `"_id"`
 
-Field name for record IDs. Change only if `_id` conflicts with your data schema.
+Controls two things depending on `id_generation`:
+
+- **Output field name** — the name of the ID field written to every output record,
+  regardless of strategy.
+- **Source field name** — when `id_generation="natural"`, the field transmog reads
+  from each source record to use as that record's ID.
+
+For all other strategies (`"random"`, `"hash"`, composite list), the value is only
+used as the output field name — no source field is read.
+
+Change this only if `_id` conflicts with your data schema.
 
 ### parent_field
 
 **Type:** `str`
 **Default:** `"_parent_id"`
 
-Field name for parent references in child tables. Change only if `_parent_id`
-conflicts with your data schema.
+Controls the **output field name** written on child records to reference their
+parent's ID. This is purely an output concern — it does not read from or target
+any field in the source data. The parent-child link is established automatically
+from the nesting structure.
+
+Change this only if `_parent_id` conflicts with your data schema.
+
+:::{note}
+`id_field`, `parent_field`, and `time_field` must all be distinct. Supplying the
+same name for any two raises a `ConfigurationError`.
+:::
 
 ### time_field
 
diff --git a/docs/ids.md b/docs/ids.md
index 364e9c9..dd754ff 100644
--- a/docs/ids.md
+++ b/docs/ids.md
@@ -85,7 +85,12 @@ assert result1.main[0]["_id"] == result2.main[0]["_id"]
 
 ## Metadata Field Names
 
-Customize the names of metadata fields:
+`id_field`, `parent_field`, and `time_field` control the **names of metadata
+columns in the output**. They do not affect how source data is read, with one
+exception: `id_field` doubles as the source field name when
+`id_generation="natural"` (see [Natural IDs](#natural-ids) above).
+
+Customize these names when the defaults conflict with your data schema:
 
 ```python
 config = tm.TransmogConfig(
@@ -100,6 +105,9 @@ print(result.main[0])
 # {'name': 'Product', 'record_id': '...', '_created_at': '...'}
 ```
 
+All three names must be distinct. Supplying the same value for any two raises a
+`ConfigurationError`.
+
 Disable timestamp tracking:
 
 ```python
@@ -109,7 +117,9 @@ result = tm.flatten(data, config=config)
 
 ## Parent-Child Relationships
 
-Child records reference their parents through the parent ID field:
+Child records reference their parents through the `parent_field` output column.
+This link is built automatically from the nesting structure — no configuration
+beyond the field name is required.
 
 ```python
 result = tm.flatten(data, name="products")

From 34cab9c924adb05b13f1e7f0842c4f58ad733aec Mon Sep 17 00:00:00 2001
From: Scott Draper <admin@scottdraper.io>
Date: Sat, 14 Mar 2026 11:33:39 -0600
Subject: [PATCH 2/2] Update GitHub python workflows to trigger only on certain
 files

---
 .github/workflows/benchmark.yml | 5 +++++
 .github/workflows/main.yml      | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
index f889257..18d0853 100644
--- a/.github/workflows/benchmark.yml
+++ b/.github/workflows/benchmark.yml
@@ -5,6 +5,11 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'scripts/**'
+      - 'pyproject.toml'
   workflow_dispatch:
 
 jobs:
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 831542a..26c0f64 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -5,6 +5,11 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'scripts/**'
+      - 'pyproject.toml'
   workflow_dispatch:
 
 jobs: