smarter_csv 1.17.2 → 1.17.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e665f0dc98db44950aa9cbb2cac430068e91df8886062068413dfbcefc74fc3
-  data.tar.gz: def43fb66886b16ec13bd429b4fd6923b09aa1a01757a696390a38c18b59fa31
+  metadata.gz: ec50e8539c6872f9c86c25eabc2982e39846ad07dc5a21021fc687c7661f8084
+  data.tar.gz: 977ce04d8dd225b6042ea03ad0c174305f3ea122340fad052e2c2ada440d6400
 SHA512:
-  metadata.gz: 2fb7793ed4eca64cfef1f7dd82a417b44988832280b373c1748213d9f7c879cd0a2d17c4e3b72c82be6acedb01b0fec26b70e6daaefb645ee2c3bf64b7aedcd8
-  data.tar.gz: a0b8842d5a69d8526af81d4e2a64c31fd6a54d6d610c5ce0dbb16298dfd03c3d296546c049a4a76a710908390ec1ea1739bc7530b1ab652c7ead1ceaa02b431d
+  metadata.gz: 0452dc7f15ab31b0cdfad83ca718e17e6456cf6c9826d177e606c5924f3ec72a155c86ee6f9f938540fe3b2ed8f694a981c95cf775b5a38d7f7e44318bc453a3
+  data.tar.gz: c1c9732d6d4393fb2ffa995f0c7bb73cd60f566132d487a86007f8a5a623257365c2324ed894a5b38d681df7cfab67069d9fa2e61fd525ba51675954ddadad7a

data/CHANGELOG.md

@@ -1,11 +1,40 @@
 
 # SmarterCSV 1.x Change Log
 
+> [!TIP]
+> **Upgrading?** The [SmarterCSV Upgrade Wizard](https://tilo.github.io/smarter_csv/upgrade_wizard.html) walks you through what (if anything) you need to change for your specific version. Most hops do not require any changes.
+
+## 1.17.3 (2026-05-26)
+
+RSpec tests: **2,274→ 2,277** (+3 tests)
+
+* No functional changes
+* added 3 test cases
+
+### Improvements
+* DRY-up C-code
+* no performance changes on the C-path
+
+### Performance
+* performance improvement on the Ruby-path
+
+  | File                              | RB-path      |
+  |-----------------------------------|--------------|
+  | PEOPLE_IMPORT_B / PEOPLE_IMPORT_C | 13.5% faster |
+  | tab_separated_60k                 | 13.2% faster |
+  | sample_100k                       | 10.3% faster |
+  | multi_char_separator              | 9.0% faster  |
+  | utf8_multibyte                    | 7.1% faster  |
+  | many_empty_fields                 | 6.7% faster  |
+  | PEOPLE_IMPORT_NC                  | 5.2% faster  |
+  | sensor_data                       | 4.5% faster  |
+
+
 ## 1.17.2 (2026-05-21)
 
 RSpec tests: **2,220→ 2,274** (+54 tests)
 
-### Bug Fix
+### Bug Fixes
 
   - fixed [Issue #334](https://github.com/tilo/smarter_csv/issues/334) with escaped double quote followed by comma. Thanks to [conorg](https://github.com/conorg)
   - fixed bug when using `headers: { except: }`
@@ -73,6 +102,16 @@ Measured against 1.16.4 (Apple M4, Ruby 3.4.7):
 
 Per-file breakdown: [`docs/releases/1.17.0/performance_notes.md`](docs/releases/1.17.0/performance_notes.md).
 
+## 1.16.6 (2026-05-21)
+
+RSpec tests: **1,467 → 1,591** (+124 tests)
+
+### Bug Fixes
+
+  - fixed [Issue #334](https://github.com/tilo/smarter_csv/issues/334) with escaped double quote followed by comma. Thanks to [conorg](https://github.com/conorg)
+  - fixed bug when using `headers: { except: }`
+  - added more tests
+
 ## 1.16.5 (2026-05-17)
 
 ### Bug Fix
@@ -164,23 +203,42 @@ RSpec tests: **1,247 → 1,410** (+163 tests)
 
 * Added 163 tests covering new features and corner cases
 
-## 1.16.0 (2026-03-12) — Minor Breaking Change
+## 1.16.0 (2026-03-12) — improved RFC 4180 quote handling, new APIs, large performance gains
 
 [Full details](docs/releases/1.16.0/changes.md) · [Benchmarks](docs/releases/1.16.0/benchmarks.md) · [Performance notes](docs/releases/1.16.0/performance_notes.md)
 
 RSpec tests: **714 → 1,247** (+533 tests)
 
-### Minor Breaking Change
+### (Bug Fix) `quote_boundary:` — new default for how mid-field quotes are handled
+
+**In short — most users will see incorrect output silently improve. If your CSV files don't contain stray `"` characters in the middle of unquoted fields, you are not affected. If they do, the new default produces correct output where the old default produced corrupted output.**
 
-New option **`quote_boundary:`**
-* defaults to `:standard`**: quotes are now only recognized as field delimiters at field boundaries;
-  mid-field quotes are treated as literal characters.
+A new option `quote_boundary:` controls when a `"` character marks the start or end of a quoted field versus when it's a literal character inside the field.
 
-  This aligns SmarterCSV with RFC 4180 and other CSV libraries. In practice, mid-field quotes
-  were already producing silently corrupt output in previous versions — so most users will see
-  correct behavior improve, not regress.
+* `quote_boundary: :standard` (the new default) — quotes are only recognized as field delimiters at field boundaries (start of a field, or immediately before `col_sep` / end of line). A `"` that appears in the middle of an unquoted field is treated as a literal character. This matches RFC 4180 and Ruby's standard `CSV` library.
+* `quote_boundary: :legacy` — **not recommended.** Restores the pre-1.16.0 behavior, where any `"` could open a quoted region. This is the behavior that produced silently corrupt output on files with stray mid-field quotes; it exists only as an escape hatch for code that built workarounds on top of the buggy output. New code should never use this.
 
-* Use `quote_boundary: :legacy` only in exceptional cases to restore previous behavior. See [Parsing Strategy](../../parsing_strategy.md).
+In practice, the old `:legacy` behavior was silently producing corrupt output whenever a CSV file contained a stray mid-field `"` — so for most users this change makes output **correct** where it was wrong before, not the other way around.
+
+#### You are NOT affected if:
+  - Your CSV files don't contain any `"` characters mid-field (the common case).
+  - Your CSV files quote fields cleanly per RFC 4180 (well-formed `"..."` around each quoted field, no stray quotes inside other fields).
+
+#### You are affected if:
+  - Your CSV files contain stray `"` characters in the middle of unquoted fields (e.g. `5'6"`, `Joe "the Hat" Smith` without surrounding quotes), **and** you had downstream code that compensated for the previously-corrupted parse output.
+
+#### How to migrate
+
+For almost everyone: do nothing. Upgrade and observe that the output is the same or more correct.
+
+The `quote_boundary: :legacy` option exists only as a short-term escape hatch — **we do not advise using it**, because it re-enables the buggy parse behavior that motivated this change. If your code built workarounds on top of the previously-corrupted output, the right fix is to remove those workarounds and rely on the new `:standard` behavior, not to opt back into the bug:
+
+```ruby
+# Only as a temporary escape hatch — not recommended for new code:
+SmarterCSV.process('file.csv', quote_boundary: :legacy)
+```
+
+See [Parsing Strategy](docs/parsing_strategy.md) for details on how each mode handles edge cases.
 
 ### Performance
 
@@ -399,44 +457,90 @@ _worldcities.csv is [from here](https://simplemaps.com/data/world-cities)_
 ## 1.13.1 (2024-12-12)
   * fix bug with SmarterCSV.generate with `force_quotes: true` ([issue 294](https://github.com/tilo/smarter_csv/issues/294))
 
-## 1.13.0 (2024-11-06) ⚡ POTENTIALLY BREAKING ⚡
-  
-  CHANGED DEFAULT BEHAVIOR
-  ========================
-  The changes are to improve robustness and to reduce the risk of data loss
+## 1.13.0 (2024-11-06) — Three default-behavior changes that prevent silent data loss
 
-  * implementing auto-detection of extra columns (thanks to James Fenley)
+This release flipped three defaults so that SmarterCSV no longer silently loses data in three specific edge cases. For most users this is a quiet improvement — files that used to lose rows or columns silently now parse correctly with no code changes. Each change below has a short "affected if / not affected if" so you can skip past it quickly.
 
-  * improved handling of unbalanced quote_char in input ([issue 288](https://github.com/tilo/smarter_csv/issues/288)) thanks to Simon Rentzke), and ([issue 283](https://github.com/tilo/smarter_csv/issues/283)) thanks to James Fenley, Randall B, Matthew Kennedy)
-    -> SmarterCSV will now raise `SmarterCSV::MalformedCSV` for unbalanced quote_char.
+The motivation for all three changes is the same: data loss should never be silent. Either parse it correctly, or raise loudly.
 
-  * bugfix / improved handling of extra columns in input data ([issue 284](https://github.com/tilo/smarter_csv/issues/284)) (thanks to James Fenley)
-   
-    * previous behavior:
-      when a CSV row had more columns than listed in the header, the additional columns were ignored
+### Change 1 (Bug Fix): extra columns in a row are auto-named instead of dropped
 
-    * new behavior:
-      * new default behavior is to auto-generate additional headers, e.g. :column_7, :column_8, etc
-      * you can set option `:strict` to true in order to get a `SmarterCSV::MalformedCSV` exception instead
+(Thanks to James Fenley, [issue #284](https://github.com/tilo/smarter_csv/issues/284).)
 
-  * setting `user_provided_headers` now implies `headers_in_file: false` ([issue 282](https://github.com/tilo/smarter_csv/issues/282))
-    
-    The option `user_provided_headers` can be used to specify headers when there are none in the input, OR to completely override headers that are in the input (file).
+If a CSV row had more columns than the header (e.g. header has 6 columns, a row has 8), the extras used to be **silently dropped**. As of 1.13.0 they survive as `:column_7`, `:column_8`, etc.
+
+#### You are NOT affected if:
+  - Your CSV files have exactly as many columns per row as headers (the common case).
+
+#### You are affected if:
+  - Your CSV files have rows with extra columns past the header **and** your code expects only the header-listed keys.
+
+#### How to migrate
+
+If you want the old "ignore extras" behavior, drop the extra keys yourself. If you want loud failure instead, use the strict mode:
+
+```ruby
+# Raise SmarterCSV::MalformedCSV on extra columns:
+SmarterCSV.process('file.csv', strict: true)
+```
+
+(In 1.16.0 this option was renamed to `missing_headers: :raise`, but `strict: true` still works.)
+
+### Change 2 (Bug Fix): unbalanced quotes raise `MalformedCSV` instead of producing garbage
+
+(Thanks to Simon Rentzke, James Fenley, Randall B, and Matthew Kennedy. Issues [#283](https://github.com/tilo/smarter_csv/issues/283), [#288](https://github.com/tilo/smarter_csv/issues/288).)
+
+Files with an unbalanced `quote_char` (an opening `"` with no matching close) used to parse to corrupted output. As of 1.13.0 they raise `SmarterCSV::MalformedCSV`.
+
+#### You are NOT affected if:
+  - Your CSV files have well-formed quotes (the common case).
+
+#### You are affected if:
+  - Some of your input files have unbalanced quotes and you used to silently live with the garbled output.
+
+#### How to migrate
 
-    SmarterCSV is now using a safer default behavior.
+If you need to keep processing other files even when one is malformed, rescue the new exception:
 
-    * previous behavior:
-      Setting `user_provided_headers` did not change the default `headers_in_file: true`
-      If the input had no headers, this would cause the first line to be erroneously treated as a header, and the user could lose the first row of data.
+```ruby
+begin
+  SmarterCSV.process('file.csv')
+rescue SmarterCSV::MalformedCSV => e
+  warn "Skipping malformed file: #{e.message}"
+end
+```
 
-    * new behavior:
-      Setting `user_provided_headers` sets`headers_in_file: false`
-      a) Improved behavior if there was no header in the input data.
-      b) If there was a header in the input data, and `user_provided_headers` is used to override the headers in the file, then please explicitly specify `headers_in_file: true`, otherwise you will get an extra hash which includes the header data.
+### Change 3 (Bug Fix): `user_provided_headers:` now implies `headers_in_file: false`
 
-    IF you set `user_provided_headers` and the file has a header, then provide `headers_in_file: true` to avoid getting that extra record.
+([Issue #282](https://github.com/tilo/smarter_csv/issues/282).)
 
-   * improved documentation for handling of numeric columns with leading zeroes, e.g. ZIP codes. ([issue #151](https://github.com/tilo/smarter_csv/issues/151) thanks to David Moles). `convert_values_to_numeric: { except: [:zip] }` will  return a string for that column instead (since version 1.10.x)
+This one fixes a quiet footgun: if you passed `user_provided_headers:` and the file had **no** header row, SmarterCSV used to treat the first data row as a header and silently drop it. As of 1.13.0, setting `user_provided_headers:` automatically sets `headers_in_file: false`, so the first row is treated as data — which is what you almost always wanted.
+
+#### You are NOT affected if:
+  - You don't use `user_provided_headers:`.
+  - You use `user_provided_headers:` with files that have no header line (the common case — that's what the option is for).
+
+#### You are affected if:
+  - You pass `user_provided_headers:` **and** your CSV file **does** have a header line that needs to be skipped.
+
+#### How to migrate
+
+If your file has a header line **and** you're overriding it with `user_provided_headers:`, add `headers_in_file: true` explicitly so the existing header line is skipped:
+
+```ruby
+# File has a header row that you want to override:
+SmarterCSV.process(
+  'file.csv',
+  user_provided_headers: [:id, :name, :email],
+  headers_in_file: true,    # skip the header row in the file
+)
+```
+
+Without `headers_in_file: true`, you will get an extra hash at the top of your results containing the file's original header strings as values — that's the symptom to look for.
+
+### Documentation
+
+* Improved documentation for handling numeric columns with leading zeroes (e.g. ZIP codes). Use `convert_values_to_numeric: { except: [:zip] }` to keep that column as a string. (Available since 1.10.x.) Thanks to David Moles, [issue #151](https://github.com/tilo/smarter_csv/issues/151).
 
 ## 1.12.1 (2024-07-10)
   * Improved column separator detection by ignoring quoted sections [#276](https://github.com/tilo/smarter_csv/pull/276) (thanks to Nicolas Castellanos)
@@ -490,23 +594,66 @@ _worldcities.csv is [from here](https://simplemaps.com/data/world-cities)_
 ## 1.10.1 (2024-01-07)
   * fix incorrect warning about UTF-8 (issue #268, thanks hirowatari)
 
-## 1.10.0 (2023-12-31) ⚡ BREAKING ⚡
+## 1.10.0 (2023-12-31) — Behavior changes for `user_provided_headers:` and duplicate headers
 
-  * BREAKING CHANGES:
-    
-    Changed behavior:
-     + when `user_provided_headers` are provided:
-       * if they are not unique, an exception will now be raised
-       * they are taken "as is", no header transformations can be applied
-       * when they are given as strings or as symbols, it is assumed that this is the desired format
-       * the value of the `strings_as_keys` options will be ignored
-         
-     + option `duplicate_header_suffix` now defaults to `''` instead of `nil`.
-       * this allows automatic disambiguation when processing of CSV files with duplicate headers, by appending a number
-       * explicitly set this option to `nil` to get the behavior from previous versions.
-
-  * performance and memory improvements
-  * code refactor
+Two small behavior changes plus performance and memory improvements. Most users are not affected. Read on for who needs to look closer.
+
+### Change 1 (Improvement): `user_provided_headers:` is now taken literally (no transformations, no duplicates)
+
+**In short — if you use `user_provided_headers:`, write the list in the exact form you want the result keys (all symbols *or* all strings), and make sure there are no duplicates. For most users this is already what you were doing.**
+
+Before 1.10.0, any list you passed as `user_provided_headers:` was run through the same header pipeline as in-file headers — `strings_as_keys` could flip strings to symbols, etc. Duplicates were silently accepted. As of 1.10.0, the list is used **literally**: no transformations are applied, and duplicates raise `SmarterCSV::DuplicateHeaders`.
+
+This is almost always what people actually wanted: if you're explicitly listing the headers, you want *those* headers, not a transformed version of them.
+
+#### You are NOT affected if:
+  - You don't use `user_provided_headers:`.
+  - Your `user_provided_headers:` list is already in the form you want (all symbols *or* all strings, no duplicates).
+  In these cases, you can just upgrade without any code changes.
+
+#### You are affected if either is true:
+  - You pass `user_provided_headers:` **and** relied on `strings_as_keys:` to flip between string/symbol keys.
+  - You pass `user_provided_headers:` **and** had accidental duplicates in the list that the library used to silently accept (this case would be very odd).
+
+#### How to migrate
+
+```ruby
+# If you want symbol keys, write symbols directly:
+SmarterCSV.process('file.csv', user_provided_headers: [:id, :name, :email])
+
+# If you want string keys, write strings directly:
+SmarterCSV.process('file.csv', user_provided_headers: ['id', 'name', 'email'])
+```
+
+Drop any `strings_as_keys:` option you used alongside `user_provided_headers:` — it's ignored in that case now.
+
+If you see `SmarterCSV::DuplicateHeaders` after upgrading, your list has a repeat in it — fix the duplicate and you're done.
+
+### Change 2 (Improvement): duplicate headers in the CSV file are now auto-disambiguated
+
+**In short — if your input CSV has duplicate column headers, they now Just Work instead of colliding. If your files don't have duplicate headers, you are not affected.**
+
+`duplicate_header_suffix:` used to default to `nil`. Now it defaults to `''` (empty string), which means a file with headers like `name,name,name` becomes keys `name`, `name2`, `name3` automatically — no more silently overwriting earlier columns.
+
+#### You are affected if:
+  - You depended on SmarterCSV raising or failing fast when a CSV has duplicate headers (e.g. as a data-quality check at the boundary of your pipeline).
+
+#### You are NOT affected if:
+  - Your CSVs don't have duplicate headers.
+  - You already explicitly set `duplicate_header_suffix:` in your code.
+
+#### How to migrate
+
+If you want the old strict behavior, set the option explicitly to `nil`:
+
+```ruby
+SmarterCSV.process('file.csv', duplicate_header_suffix: nil)
+```
+
+### Other
+
+* Performance and memory improvements
+* Internal code refactor
 
 ## 1.9.3 (2023-12-16)
   * raise SmarterCSV::IncorrectOption when `user_provided_headers` are empty
@@ -644,13 +791,40 @@ _worldcities.csv is [from here](https://simplemaps.com/data/world-cities)_
   * fixed buggy behavior when using `remove_empty_values: false` (issue #168)
   * fixed Ruby 3.0 deprecation
 
-## 1.3.0 (2022-02-06) Breaking code change if you used `--key_mappings`
- * fix bug for key_mappings (issue #181)   
-   The values of the `key_mappings` hash will now be used "as is", and no longer forced to be symbols
+## 1.3.0 (2022-02-06)
+
+### (Bug Fix) Small change for users of the `key_mapping:` option (issue #181)
+
+**In short — if you use `key_mapping:`, this is a one-character fix per mapping. If you don't use `key_mapping:`, you are not affected.**
+
+Previously, the values in a `key_mapping:` hash were silently coerced to symbols, so `'new_name'` and `:new_name` produced the same result key. As of 1.3.0, the values are used as-is — strings stay strings, symbols stay symbols. This gives you direct control over whether the result hashes use string or symbol keys.
+
+#### You are NOT affected if any of these are true:
+  - You don't use `key_mapping:`.
+  - Your `key_mapping:` already uses symbol values (e.g. `:new_name`).
+  - Your downstream code already reads result hashes with string keys.
+  In these cases, you can just upgrade without any code changes.
+
+#### You are affected if all three are true:
+  - You pass `key_mapping:` to `SmarterCSV.process` (or `process_csv` in older code), **and**
+  - The values in that hash are strings (e.g. `'new_name'`, not `:new_name`), **and**
+  - Your downstream code reads the result hashes with symbol keys (e.g. `row[:new_name]`).
+  This needs a small code-change
+
+#### How to migrate
+
+Pick whichever is the smaller diff in your code:
+
+```ruby
+# Option A — keep symbol keys in the result (one extra colon per line):
+SmarterCSV.process('file.csv', key_mapping: { 'Old Header' => :new_name })
+#                                                             ^ add the colon
+
+# Option B — switch your reads to string keys:
+row['new_name']   # instead of row[:new_name]
+```
 
-   **Users with existing code with `--key_mappings` need to change their code** to 
-     * either use symbols in the `key_mapping` hash
-     * or change the expected keys from symbols to strings
+That's the whole migration. Everything else in 1.3.0 is source-compatible with 1.2.x.
 
 ## 1.2.9 (2021-11-22) (PULLED)
  * fix bug for key_mappings (issue #181)
@@ -677,7 +851,7 @@ _worldcities.csv is [from here](https://simplemaps.com/data/world-cities)_
  * bugfix (thanks to Joshua Smith for reporting)
 
 ## 1.2.0 (2018-01-20)
- * add default validation that a header can only appear once
+ * add default validation that a header can only appear once; raises `SmarterCSV::DuplicateHeaders` when it doesn't
  * add option `required_headers`
 
 ## 1.1.5 (2017-11-05)

data/README.md

@@ -1,7 +1,10 @@
 
 # SmarterCSV
 
-![Gem Version](https://img.shields.io/gem/v/smarter_csv) [![codecov](https://codecov.io/gh/tilo/smarter_csv/branch/main/graph/badge.svg?token=1L7OD80182)](https://codecov.io/gh/tilo/smarter_csv) [![Downloads](https://img.shields.io/gem/dt/smarter_csv)](https://rubygems.org/gems/smarter_csv) [![RubyGems](https://img.shields.io/badge/RubyGems-smarter__csv-brightgreen?logo=rubygems&logoColor=white)](https://rubygems.org/gems/smarter_csv) [![Ruby Toolbox](https://img.shields.io/badge/Ruby%20Toolbox-smarter__csv-brightgreen)](https://www.ruby-toolbox.com/projects/smarter_csv)
+![Gem Version](https://img.shields.io/gem/v/smarter_csv) [![codecov](https://codecov.io/gh/tilo/smarter_csv/branch/main/graph/badge.svg?token=1L7OD80182)](https://codecov.io/gh/tilo/smarter_csv) [![Downloads](https://img.shields.io/gem/dt/smarter_csv)](https://rubygems.org/gems/smarter_csv) [![RubyGems](https://img.shields.io/badge/RubyGems-smarter__csv-brightgreen?logo=rubygems&logoColor=white)](https://rubygems.org/gems/smarter_csv) [![Ruby Toolbox](https://img.shields.io/badge/Ruby%20Toolbox-smarter__csv-brightgreen)](https://www.ruby-toolbox.com/projects/smarter_csv) [![Upgrade Wizard](https://img.shields.io/badge/Upgrade%20Wizard-Try%20it-2c7a2c?style=flat)](https://tilo.github.io/smarter_csv/upgrade_wizard.html)
+
+> [!TIP]
+> **Upgrading from an older version?** Use the [SmarterCSV Upgrade Wizard](https://tilo.github.io/smarter_csv/upgrade_wizard.html) to walk through what (if anything) you need to change for your specific version. Most hops do not require any changes.
         
   SmarterCSV is a high-performance CSV ingestion and generation for Ruby, focused on fast end-to-end CSV ingestion of real-world data — no silent failures, no surprises, not just tokenization.
 

data/UPGRADING.md

@@ -0,0 +1,251 @@
+# Upgrading SmarterCSV
+
+> [!TIP]
+> Prefer the interactive [Upgrade Wizard](https://tilo.github.io/smarter_csv/upgrade_wizard.html) for a guided walk-through with Yes/No questions.  
+> This document is auto-generated from `CHANGELOG.md` and `docs/upgrade_path.json` by `bin/gen-upgrading-md`.
+
+## How to use this guide
+
+1. Find your current version below. **Newest releases appear first; older ones further down.**
+2. Read each series section between yours and the latest at the top. For each one, check whether any **If** conditions apply to your code.
+3. If none apply, you can upgrade all the way through that series with no code changes.
+
+Prefer an interactive walk-through? The [Upgrade Wizard](https://tilo.github.io/smarter_csv/upgrade_wizard.html) asks one question at a time and only shows the migration steps that apply to your code.
+
+**Latest release:** `1.17.3` (in the `1.17.x` series).
+
+---
+
+## 1.17.x — latest series
+
+**Versions in this series:**  
+[1.17.0, 1.17.1, 1.17.2, 1.17.3]
+
+**Latest release:** `1.17.3`
+
+Update your Gemfile to:
+
+```ruby
+gem 'smarter_csv', '~> 1.17.0'
+```
+
+Then run `bundle update smarter_csv`.
+
+## Series 1.16 → 1.17
+
+**Coming from any 1.16 version:**  
+[1.16.0, 1.16.1, 1.16.2, 1.16.3, 1.16.4, 1.16.5, 1.16.6]
+
+> ⚠️ **In-series notes** worth checking if you're upgrading through one of these:
+> - **1.16.1:** **Fibers:** `SmarterCSV.errors` uses `Thread.current` for storage, which is **shared across all fibers running in the same thread**. If you process CSV files concurrently in fibers (e.g. with `Async`, `Falcon`, or manual `Fiber` scheduling), `SmarterCSV.errors` may return stale or wrong results. **Use `SmarterCSV::Reader` directly** — errors are scoped to the reader instance and are always correct regardless of fiber context.
+> - **1.16.2:** If your code references auto-generated keys for blank headers, update those to use the absolute column position.
+
+**Upgrading to 1.17.x** (latest: `1.17.3`): you can upgrade all the way — no code changes needed.
+
+---
+
+## Series 1.15 → 1.16
+
+**Coming from any 1.15 version:**  
+[1.15.0, 1.15.1, 1.15.2, 1.15.3]
+
+**Upgrading to 1.16.x** (latest: `1.16.6`):
+
+- **If** your CSV files contain stray `"` characters in the middle of unquoted fields:  
+  → verify the output is now correct — 1.16.0 treats them as literal (RFC 4180). Output gets more correct for almost everyone; the temporary escape hatch `quote_boundary: :legacy` exists if your downstream code depended on the previously-corrupted output (not recommended for new code).
+
+---
+
+## Series 1.14 → 1.15
+
+**Coming from any 1.14 version:**  
+[1.14.0, 1.14.1, 1.14.2, 1.14.3, 1.14.4]
+
+**Upgrading to 1.15.x** (latest: `1.15.3`):
+
+- **If** your Ruby version is 2.5 or older:  
+  → upgrade Ruby to 2.6 or newer — 1.15.0 dropped support for Ruby 2.5.
+    
+    The migration is small: Ruby 2.5 reached end-of-life in March 2021 (no more security fixes anywhere), and Ruby 2.5 → 2.6 is API-compatible for nearly all code. Update your `.ruby-version` or the `ruby` line in your `Gemfile`, run `bundle install`, and you're done. Most users jump straight to a current Ruby (3.x).
+
+---
+
+## Series 1.13 → 1.14
+
+**Coming from any 1.13 version:**  
+[1.13.0, 1.13.1]
+
+**Upgrading to 1.14.x** (latest: `1.14.4`): you can upgrade all the way — no code changes needed.
+
+---
+
+## Series 1.12 → 1.13
+
+**Coming from any 1.12 version:**  
+[1.12.0, 1.12.1]
+
+**Upgrading to 1.13.x** (latest: `1.13.1`):
+
+- **If** your CSV rows can have more columns than the header AND your code expects only header-listed keys:  
+  → filter out the new auto-generated `:column_N` keys, or pass `strict: true` to raise on extras — 1.13.0 keeps extra columns instead of dropping them silently.
+
+- **If** any of your input files might have unbalanced quotes:  
+  → wrap calls in `rescue SmarterCSV::MalformedCSV` — 1.13.0 now raises instead of producing garbled output.
+
+- **If** you pass `user_provided_headers:` AND your file has a header line that should be skipped:  
+  → also pass `headers_in_file: true` explicitly — 1.13.0 made `user_provided_headers:` imply `headers_in_file: false` by default.
+
+---
+
+## Series 1.11 → 1.12
+
+**Coming from any 1.11 version:**  
+[1.11.0, 1.11.2]
+
+**Upgrading to 1.12.x** (latest: `1.12.1`):
+
+- **If** you call `SmarterCSV.process` and need to inspect headers / warnings / errors after parsing:  
+  → switch to using `reader = SmarterCSV::Reader.new(file, options); reader.process`.
+    
+    Version 1.11 class-level accessors `SmarterCSV.headers` / `SmarterCSV.raw_header` are gone in 1.12.0 — if you used those, see the next question.
+
+- **If** you call `SmarterCSV.raw_headers` or `SmarterCSV.headers`:  
+  → switch to instantiating `SmarterCSV::Reader` and reading `reader.raw_headers` / `reader.headers` — 1.12.0 moved these off the class-level API.
+
+---
+
+## Series 1.10 → 1.11
+
+**Coming from any 1.10 version:**  
+[1.10.0, 1.10.1, 1.10.2, 1.10.3]
+
+**Upgrading to 1.11.x** (latest: `1.11.2`): you can upgrade all the way — no code changes needed.
+
+---
+
+## Series 1.9 → 1.10
+
+**Coming from any 1.9 version:**  
+[1.9.0, 1.9.2, 1.9.3]
+
+**Upgrading to 1.10.x** (latest: `1.10.3`):
+
+- **If** you use `user_provided_headers:`:  
+  → write the list in the exact final form you want (all symbols *or* all strings) — 1.10.0 stopped applying additional transformations. `strings_as_keys:` is ignored alongside it.
+
+- **If** your `user_provided_headers:` list contains duplicate entries:  
+  → remove the duplicates — 1.10.0 raises `SmarterCSV::DuplicateHeaders`.
+
+- **If** you depended on duplicate-header detection failing fast:  
+  → pass `duplicate_header_suffix: nil` explicitly — 1.10.0 changed the default to `''` (it auto-disambiguates duplicates as `name`, `name2`, ...).
+
+---
+
+## Series 1.8 → 1.9
+
+**Coming from any 1.8 version:**  
+[1.8.0, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.8.5]
+
+**Upgrading to 1.9.x** (latest: `1.9.3`):
+
+- **If** you rescue `SmarterCSV::MissingHeaders`:  
+  → rename it to `SmarterCSV::MissingKeys` — 1.9.0 renamed the error.
+
+- **If** you use `key_mapping:` and want to allow some mapped headers to be missing:  
+  → pass `silence_missing_keys: true` — 1.9.0 now raises `MissingKeys` for unmapped headers (this makes them optional).
+
+---
+
+## Series 1.7 → 1.8
+
+**Coming from any 1.7 version:**  
+[1.7.0.pre1, 1.7.0.pre5, 1.7.1, 1.7.2, 1.7.3, 1.7.4]
+
+**Upgrading to 1.8.x** (latest: `1.8.5`):
+
+- **If** you accept CSV files from users or other external sources where the column separator might not be a comma (e.g. locale-specific exports using `;` or tab), or where a file might have only one column:  
+  → wrap your `SmarterCSV.process` calls in `rescue SmarterCSV::NoColSepDetected` — 1.8.0 made `col_sep: :auto` and `row_sep: :auto` the new defaults, but in rare cases it raises when separators could not be found.
+
+---
+
+## Series 1.6 → 1.7
+
+**Coming from any 1.6 version:**  
+[1.6.0, 1.6.1]
+
+**Upgrading to 1.7.x** (latest: `1.7.4`): you can upgrade all the way — no code changes needed.
+
+---
+
+## Series 1.5 → 1.6
+
+**Coming from any 1.5 version:**  
+[1.5.0, 1.5.1, 1.5.2]
+
+**Upgrading to 1.6.x** (latest: `1.6.1`):
+
+- **If** you rescue an exception when `key_mapping:` has an unused key:  
+  → remove that rescue clause — 1.6.1 changed this from an exception to a warning.
+
+---
+
+## Series 1.4 → 1.5
+
+**Coming from any 1.4 version:**  
+[1.4.0, 1.4.2]
+
+**Upgrading to 1.5.x** (latest: `1.5.2`):
+
+- **If** you relied on lines starting with `#` being treated as comments:  
+  → pass `comment_regexp: /\A#/` explicitly — 1.5.0 changed the default to `nil`.
+
+---
+
+## Series 1.3 → 1.4
+
+**Coming from any 1.3 version:**  
+[1.3.0]
+
+**Upgrading to 1.4.x** (latest: `1.4.2`): you can upgrade all the way — no code changes needed.
+
+---
+
+## Series 1.2 → 1.3
+
+**Coming from any 1.2 version:**  
+[1.2.0, 1.2.3, 1.2.4, 1.2.5, 1.2.6, 1.2.7, 1.2.8]
+
+**Upgrading to 1.3.x** (latest: `1.3.0`):
+
+- **If** you use `key_mapping:`:  
+  → switch hash values to symbols (or update downstream reads to use string keys) — 1.3.0 stopped silently coercing values to symbols.
+
+---
+
+## Series 1.1 → 1.2
+
+**Coming from any 1.1 version:**  
+[1.1.0, 1.1.1, 1.1.2, 1.1.3, 1.1.4, 1.1.5]
+
+**Upgrading to 1.2.x** (latest: `1.2.8`):
+
+- **If** your CSV files have duplicate header names:  
+  → rename the duplicates, or be ready to rescue `SmarterCSV::DuplicateHeaders` — 1.2.0 added default validation that each header appears only once and raises this exception when it doesn't.
+
+---
+
+## Series 1.0 → 1.1
+
+**Coming from any 1.0 version:**  
+[1.0.0.pre1, 1.0.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6, 1.0.7, 1.0.8, 1.0.9, 1.0.10, 1.0.11, 1.0.12, 1.0.14, 1.0.15, 1.0.16, 1.0.17, 1.0.18, 1.0.19]
+
+**Upgrading to 1.1.x** (latest: `1.1.5`):
+
+- **If** you set `headers_in_file: false`:  
+  → also provide `user_provided_headers:` — 1.1.0 now raises an error if you set the former without the latter.
+
+---
+
+---
+
+Questions? Open an issue: <https://github.com/tilo/smarter_csv/issues>.