docs(export): correct the bundle layout, the CSV import claim and the tracked-day loss - #999
Merged
Merged
Conversation
… tracked-day loss Checked against origin/release/2.2.0. The CSV column tables are all still exact -- 41 intake columns, 13 activity, 9 tracked-day, in order -- as is the dialect section. The layout and the round-trip section were not. - **The bundle is format-exclusive.** Settings -> Export offers a JSON / CSV toggle and writes one or the other; no bundle the app produces has ever carried a CSV next to its JSON counterpart. The doc described a single zip with both side by side, each CSV a "flat companion" -- so a tool author unzipping expecting six files finds three. Split into a JSON table and a CSV table. - **Four artefacts were missing:** weight_log.json and custom_activity_templates.json from the JSON bundle, and the recipe_images/ and meal_images/ directories carrying user photos. - **CSV import shipped.** ImportDataUsecase.importDataCsv reads all three CSVs and is wired to the same toggle. The doc said the importer "reads the JSON files and ignores the CSV companions" and offered CSV import as future work "if there's demand". - **Tracked days do not round-trip, and the doc promised they did.** trackedDayColumns has 9 entries against TrackedDayDBO's 19 fields: the ten per-nutrient goals added by #173 have no column and are dropped. The cited test does not pin what the doc claimed, because its tracked-day group never sets them. Now stated, with a pointer to use JSON for restores. - **"User profile (height, weight, birthday, PAL, goal) is not included"** read as "your weight data is not in the bundle". The profile box is excluded, but weight history is exported as weight_log.json. Separated. Refs #991
4 tasks
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The updated ZIP layout section incorrectly claims photos are included in both JSON and CSV bundles and references a non-existent path missing the lib/ prefix.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Updates docs/export-format.md to correctly describe the app’s export/import ZIP contents and the actual behavior of JSON vs CSV bundles, aligning the documentation with the current exporter/importer implementation.
Changes:
- Split the ZIP layout description into distinct JSON bundle vs CSV bundle tables (format-exclusive export).
- Corrected the prior claim that CSV import is read-only by documenting the existing CSV import path.
- Documented the tracked-day CSV round-trip limitation (per-nutrient goals are dropped) and pointed readers to JSON for lossless restore.
File summaries
| File | Description |
|---|---|
| docs/export-format.md | Corrects export bundle layout and import/round-trip claims for JSON vs CSV formats. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+40
to
+45
| Either bundle also carries any user-attached photos, under `recipe_images/` and | ||
| `meal_images/`. | ||
|
|
||
| The **profile box** — height, birthday, PAL, goal — is intentionally not | ||
| included; see `core/data/data_source/user_data_source.dart`. Note this is the | ||
| profile only: your logged **weight history** *is* exported, as `weight_log.json`. |
Copilot caught it, and the code agrees: `_addUserImageIfPresent` sits inside the `format == ExportFormat.json` branch of `exportData`, and `importDataCsv` has no image-restore step at all. The page said either bundle carries them, which would have cost someone their photos on a CSV round trip. Also prefixes the profile-box path with `lib/`, matching every other path on the page.
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The change is documentation-only and the updated statements match the current export/import implementation (including CSV import and JSON-only artifacts).
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
- Review effort level: Lite
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Third of the three docs in #991. Checked against
origin/release/2.2.0.What survived: all three CSV column tables match
CsvDataExporterexactly — 41 intake columns, 13 activity, 9 tracked-day, in order — and the dialect section matches_cellandCsvRowParserincluding the decimal-comma handling. Those are the parts an external tool actually parses, and they were right.The premise was wrong
The doc described one zip containing JSON and CSV side by side, each CSV a "flat companion" to its JSON. The export is format-exclusive: a JSON/CSV toggle in
export_import_dialog.dartpicks one, andexport_data_usecase.dartwrites one or the other. No bundle the app has ever produced contains both. Someone writing a tool against this page unzips expecting six files and finds three.Now split into a JSON-bundle table and a CSV-bundle table.
Two claims that were the opposite of the truth
CSV import exists.
ImportDataUsecase.importDataCsvreads all three CSVs and is wired to the same toggle as the export. The page said the importer "reads the JSON files and ignores the CSV companions", and offered "Import CSV (intakes / activities / tracked days)" as future work "if there's demand".Tracked days do not round-trip. The page promised CSV export+parse yields structurally equal DBOs and cited a test for it.
trackedDayColumnshas 9 entries;TrackedDayDBOhas 19 fields. The ten per-nutrient goals from #173 — fibre, saturated fat, sugars, sodium, calcium, iron, potassium, magnesium, B12, vitamin D — have no column and are silently dropped. The cited test doesn't catch it because its tracked-day group never sets them. Anyone restoring from a CSV bundle loses those goals, and the page told them it was safe.Also
weight_log.json,custom_activity_templates.json, and therecipe_images/andmeal_images/directories.weight_log.json. The two are now separated explicitly.Checked
csv_data_exporter_test.dartpassesCsvDataExporteron the release branch#round-trip-guaranteecross-link resolvesNo runtime test reads this file, unlike
ai-architecture.mdandRELEASING.md— which is part of why it drifted this far.