docs: adds project dump restore adr - #1356
Open
somethings (lasomethingsomething) wants to merge 3 commits into
Open
docs: adds project dump restore adr#1356somethings (lasomethingsomething) wants to merge 3 commits into
somethings (lasomethingsomething) wants to merge 3 commits into
Conversation
Contributor
📝 WalkthroughWalkthroughThe PR updates ADR front matter and adds ADR 0002. The new ADR defines portable project dump and restore workflows with selectable components, versioned manifests, multiple database formats, optional compression, extensible storage, and separate production backup responsibilities. ChangesADR documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1356 +/- ##
=======================================
Coverage 58.06% 58.06%
=======================================
Files 308 308
Lines 23579 23579
=======================================
Hits 13692 13692
Misses 9859 9859
Partials 28 28
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (2)
docs/adr/0002-project-dump-restore.md (2)
25-26: 🗄️ Data Integrity & Integration | 🔵 Trivial | 🏗️ Heavy liftDefine compression scope for multi-component transfers.
The existing command wraps the SQL output stream with gzip or zstd. Line 25 applies optional compression to a transfer that can contain independent components, but does not say whether compression is per component or around the complete manifest. It also does not define required codecs or restore detection. Define this contract so partial restore and hosted exchange use the same layout.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/adr/0002-project-dump-restore.md` around lines 25 - 26, Clarify the ADR’s compression contract for multi-component dump and restore operations: specify whether compression wraps the complete manifest/transfer or is applied independently per component, define the required gzip and zstd codecs, and document how restore detects the selected format. Ensure the same layout supports partial restore and hosted exchange.
27-27: 🗄️ Data Integrity & Integration | 🔵 Trivial | 🏗️ Heavy liftMake storage backend requirements testable.
Line 27 requires S3 and additional user-controlled backends, but does not define minimum operations or ownership boundaries. State how the workflow reads, writes, lists, resumes, retries, and authenticates against a backend. Otherwise
support S3is not testable and partial transfers can behave differently across backends.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/adr/0002-project-dump-restore.md` at line 27, Update the dump/restore storage requirements in the ADR to define testable backend capabilities: reading, writing, listing objects, resuming partial transfers, retrying failures, and authenticating through backend-specific mechanisms. Specify the workflow/backend ownership boundaries for these operations, while preserving support for local storage, S3, and future user-controlled backends.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0002-project-dump-restore.md`:
- Around line 19-21: The ADR currently describes a versioned manifest without
defining an implementable contract. Add a minimal normative manifest schema and
validation rules covering required fields, component identifiers, format
versions, checksums, unknown-version handling, and compatibility negotiation, or
explicitly link a follow-up specification that must be completed before
implementation. Anchor the additions to the versioned manifest and
interchange-contract sections.
- Around line 17-18: Update the ADR’s private-file transfer section to define
the default inclusion behavior, explicitly list excluded paths, and specify
sanitization rules for secrets and personally identifiable information. Clarify
that database anonymization applies only to the database dumper and does not
protect private files.
- Around line 23-24: Expand the database dump contract in the ADR around the
statement that restore supports MySQL Shell dumps: explicitly define whether
project restore accepts util.dumpInstance, util.dumpSchemas, or both, and
document the required directory layout, metadata, compression, checksums,
validation rules, and supported MySQL Shell and MySQL versions.
- Around line 15-19: Define in the ADR the database-only transfer contract:
specify when `project dump` emits the existing SQL stream versus a versioned
manifest, how users select SQL, MySQL Shell, gzip, and zstd formats, and how
`project restore` detects each supported input type, including compressed and
manifest inputs. Ensure the rules preserve existing `dump.sql` and stdout
behavior while making compatibility requirements explicit and testable.
---
Nitpick comments:
In `@docs/adr/0002-project-dump-restore.md`:
- Around line 25-26: Clarify the ADR’s compression contract for multi-component
dump and restore operations: specify whether compression wraps the complete
manifest/transfer or is applied independently per component, define the required
gzip and zstd codecs, and document how restore detects the selected format.
Ensure the same layout supports partial restore and hosted exchange.
- Line 27: Update the dump/restore storage requirements in the ADR to define
testable backend capabilities: reading, writing, listing objects, resuming
partial transfers, retrying failures, and authenticating through
backend-specific mechanisms. Specify the workflow/backend ownership boundaries
for these operations, while preserving support for local storage, S3, and future
user-controlled backends.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 6538fd26-c0f4-4ee1-ad92-69031d270534
📒 Files selected for processing (2)
docs/adr/0001-ai-command.mddocs/adr/0002-project-dump-restore.md
Soner (shyim)
requested changes
Aug 12, 2026
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0002-project-dump-restore.md`:
- Around line 47-58: Add language identifiers to the fenced code blocks in the
ADR: mark the archive layout block as text and the manifest structure example as
json, preserving their existing contents.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: e6bdaf4d-4e52-4d49-8906-7795f92d968f
📒 Files selected for processing (1)
docs/adr/0002-project-dump-restore.md
Jens (jenskueper)
approved these changes
Aug 13, 2026
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
4 participants
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.
What changed?
ADR to document decisions with PaaS+SaaS regarding proposed
project restoreworkflow behavior.Also standardizes the headings to more closely match what's used in shopware/shopware, updating the first ADR.
Why?
Get buy-in and alignment from stakeholders, drive interoperability across and support hosting models without hard-coding the CLI into corners.
How was this tested?
It's a docs change.
Related issue or discussion
Relates to #1326 and would unblock #1243.
Summary by CodeRabbit