Extra Printing Options — Learnings

L-01: Extend configuration systems rather than modifying shared parsing infrastructure

When adding CSV display-name aliases, the initial approach was to modify the shared parseScalar method signature. The correct approach was to extend the existing ColumnDef configuration with a valueAliases map, following the same pattern as header aliases. The configuration-driven approach kept changes contained and testable.

L-02: Protobuf enum alias resolution must preserve original casing

Lowercasing the resolved value for enum alias lookup makes findValueByName() a dead branch (protobuf enum names are uppercase). The alias lookup key should be lowercased for case-insensitive matching, but the resolved value must preserve casing so the fast exact-match path succeeds.

L-03: Google Workspace MCP can read and write spreadsheets directly

The Documint template mapping spreadsheet was fully readable and writable via the Google Workspace MCP server. This avoided manual spreadsheet work and ensured exact alignment between the spreadsheet data and the pdf-templates.json configuration.

L-04: Pass configuration objects whole, not decomposed

ItemCsvUploadService originally took headerAliases: Map<String, String> as a parameter. When adding valueAliases, the cleaner approach was to pass the MappingConfig object directly, letting the service extract what it needs. This keeps the constructor stable as the config grows.

L-05: Documentation CHANGELOG entries are required for PR checks

The documentation repository’s CI pipeline includes a validate-release check that fails if no new CHANGELOG version entry is present. This was not initially anticipated and required a follow-up commit.