Preserving Remote Document Versions With Local Changes

Hey guys! Let's dive into an important topic: How can we efficiently handle document versions when you're working locally and syncing with a remote source? This is crucial for a smooth editing experience. This article addresses Issue #14, focusing on preserving the remote document version while allowing for local changes.

Understanding the Need for Document Versioning

Why is this even necessary, you ask? Well, imagine you're collaborating on a document. You load it from a remote source, make some changes, and save it locally. Without proper versioning, you could easily overwrite the original remote version, losing track of what it looked like before your changes. This makes it impossible to sync your changes back to the remote registry correctly and creates potential conflicts. A solid document versioning system needs to keep track of three key states: the original remote version, the last locally saved version, and the current in-memory working version. This approach ensures that you always have a point of reference for changes and a way to reconcile local and remote updates.

Think of it like this: You're a painter working on a masterpiece. You have the original canvas (the remote version), a snapshot of your last saved progress (the intermediate version), and your current work in progress (the workspace document). Each state serves a specific purpose, allowing for a flexible and reliable workflow. We're talking about avoiding data loss and ensuring seamless collaboration. This is the heart of why we're focusing on this issue.

The Current Behavior: A Problematic Overwrite

Right now, the workspace store has a pretty straightforward, but ultimately limited, approach. It holds two document states: the original document and the current reactive workspace document. When you hit that saveDocument() button, the changes are written directly back to the original document. This means the last known remote version gets wiped out. This is a big problem, guys! You lose the ability to differentiate between what came from the remote registry and what you've saved locally. It's like erasing the blueprint of a building before starting construction; you're going to have a hard time knowing what you're building!

Let's get into a simple scenario to illustrate the problem:

1. Load a document: Grab a document from a remote source.
2. Make changes: Start editing in the reactive workspace.
3. Save the changes: Use the saveDocument() function.
4. Try to access the original: Attempt to retrieve the original remote version.
5. Observe the result: The original document has been overwritten with your saved changes. The remote version is gone!

This current behavior essentially throws away valuable information, which is a major bottleneck in any collaborative or version-controlled environment. You're left with just the latest version, which makes it tough to track changes, resolve conflicts, and generally maintain data integrity. So, we need a better solution.

Expected Behavior: A Three-Tiered Approach

Now, let's talk about what we want: a system that can handle different document states gracefully. We want a three-tiered document state model:

• Original documents: The untouched, pristine version you initially loaded from the remote registry. This is your baseline and should never be directly modified.
• Intermediate documents: The last version of the document you saved locally. This acts as a checkpoint, reflecting the most recently saved changes.
• Workspace documents: The active, in-memory version you're currently working on. This is where your unsaved changes live.

How does this improve things? When you call saveDocument(), it updates the intermediate document while preserving the original. When you call exportDocument(), it exports the intermediate (locally saved) version. When syncing with a remote registry, you compare the intermediate version against the original to see what needs to be synced. This three-tier system gives us a lot more flexibility and control. It allows us to track changes over time, resolve conflicts, and create a better user experience.

Key Functionality and Implementation

The saveDocument() function will need to update the intermediate document without touching the original. The exportDocument() will need to export from the intermediate document. The revertDocument() will need to revert to the intermediate document (last saved state), not the original remote version. When syncing with a remote registry, the system should be able to compare the intermediate version against the original to determine what needs to be pushed.

Acceptance Criteria: Ensuring the Solution Works

To make sure this works correctly, we have a set of acceptance criteria:

• Intermediate document storage: A new layer is created to store the intermediate documents.
• saveDocument() updates: The function will now update the intermediate document only.
• exportDocument() exports: It should export from the intermediate, not the original.
• revertDocument() reverts: It should revert to the intermediate state.
• Documentation update: Documentation must clearly explain the three-tier document model.

These are important to follow to ensure that the new system functions correctly and maintains the integrity of your documents.

Testing the New System: Step-by-Step

To ensure everything works smoothly, here's how we'll test the new system:

1. Load a document: Begin by loading a document into the workspace store with known content.
2. Verify the original: Check that the original document matches the initial input.
3. Make changes: Modify the reactive workspace document.
4. Call saveDocument(): Execute this function and verify that the intermediate document is updated.
5. Original remains unchanged: Confirm that the original document is still the same as the initial input.
6. Call exportDocument(): Verify it returns the intermediate (saved) version, not the original.
7. Unsaved changes: Make more changes to the workspace document that are not saved.
8. Call revertDocument(): Check that it reverts to the intermediate version, not the original.
9. Existing tests: Confirm that all existing tests still pass with the new three-tier state model.

By following these steps, we make sure that the system is doing what it is supposed to and that all of the existing functionality is still valid.

Submission Requirements

To demonstrate this, we ask that you record your screen using Cap.so (in Studio mode). Export this recording as an MP4 and drag and drop it into the issue comment below. Also, remember to consult the guide to submitting pull requests.

In essence, by implementing this three-tiered approach, we're building a more robust and user-friendly system for handling document versions and local changes, which will ultimately enhance the overall editing experience.