mirror of
https://github.com/vrtmrz/obsidian-livesync.git
synced 2026-07-23 04:52:58 +00:00
Prepare the 1.0 compatibility review flow
This commit is contained in:
vorotamoroz
@@ -0,0 +1,54 @@
|
||||
# Release notes and database compatibility gates
|
||||
|
||||
## Status
|
||||
|
||||
Accepted for the 1.0 release line.
|
||||
|
||||
## Context
|
||||
|
||||
Self-hosted LiveSync historically used two unrelated kinds of version state during start-up.
|
||||
|
||||
The plug-in SemVer was converted into a numeric major/minor value and stored in `lastReadUpdates`. The settings dialogue used that value to open the change log automatically, and offered a button which marked the release line as read. Patch versions were intentionally ignored. Pre-release identifiers containing an additional dot did not fit this numeric representation and could be interpreted as a much larger release line.
|
||||
|
||||
Separately, the internal database compatibility constant `VER` is recorded in device-local storage under a Vault-scoped key. Crossing this internal version used to set `versionUpFlash` and permanently change several automatic synchronisation settings to `false`. Replication services already reject work while `versionUpFlash` is non-empty, so changing the user's saved choices duplicated the runtime safety gate and required manual reconstruction after acknowledgement.
|
||||
|
||||
The remote `obsydian_livesync_version` document also carries the internal database version. It is a protocol and data-compatibility mechanism, not a copy of the plug-in SemVer.
|
||||
|
||||
## Decision
|
||||
|
||||
### Release notes
|
||||
|
||||
- Keep the change-log pane and render the current release history whenever it is opened.
|
||||
- Remove automatic unread-version tracking, the acknowledgement button for ordinary release notes, and automatic navigation to the change-log pane.
|
||||
- Do not derive data-compatibility behaviour from the plug-in's major, minor, patch, or pre-release identifiers.
|
||||
- Retain the saved `lastReadUpdates` field in the settings schema for backwards compatibility, but do not use it in the plug-in. It can be removed through a separately reviewed settings-schema migration if retaining it later becomes burdensome.
|
||||
|
||||
### Database compatibility
|
||||
|
||||
- Continue to use the internal database version `VER` for changes which require explicit compatibility review. Changing the plug-in SemVer alone does not increment `VER`.
|
||||
- Store the last acknowledged internal database version through Commonlib's device-local small-configuration contract under `database-compatibility-version`. Copy the legacy raw local-storage value into that contract once, then remove the legacy key after the copy has completed.
|
||||
- Initialise the marker to the current `VER` only when Commonlib identifies a genuinely new Vault with no pending review. An existing Vault with a missing or invalid marker requires review instead of being silently accepted.
|
||||
- Derive one structured pause from the acknowledged database version, Commonlib's settings-migration state, and any persisted legacy review message. Persist the generic `versionUpFlash` message without changing any automatic synchronisation setting, because Commonlib already treats that field as a replication gate.
|
||||
- Treat non-empty `versionUpFlash` as a runtime replication gate. Standard and one-shot replication must stop before remote work begins.
|
||||
- Present the reason in a dedicated dialogue after the Obsidian layout is ready. The details view is explanatory only and returns to the summary before any decision can be made. The safe default and closing either dialogue keep synchronisation paused. A persistent Notice and a command allow the dialogue to be reopened without using the settings pane.
|
||||
- Let the person read focused compatibility details without presenting the whole release history as a safety instruction. The Change Log remains a manually opened release-history pane and contains no compatibility acknowledgement control.
|
||||
- Offer an explicit resume action only when every reason is recoverable in the running implementation. An upgrade, a missing or invalid marker on an existing Vault, and a reviewed migration from an older settings schema are resumable after all devices have been updated. A downgrade from a newer acknowledged `VER`, or settings saved by a future schema, cannot be acknowledged by the older installation.
|
||||
- On resume, clear `versionUpFlash` and persist that fail-closed change before recording the current `VER` as acknowledged. If saving fails, restore the gate. Reapply settings only after the marker has advanced so that the previously configured synchronisation behaviour can resume without reconstruction.
|
||||
- Preserve the original legacy review message as a structured reason when no more specific database or settings-schema reason is available. Escape it before including it in Markdown UI.
|
||||
- Continue to reject a remote version document which is newer than the running implementation. That receiver-side check is independent of the local upgrade review.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Ordinary releases no longer force the settings dialogue to show release notes. Important operational instructions must be clear in the published release notes and any explicit migration notice.
|
||||
- SemVer pre-releases such as `1.0.0-rc.0` no longer require a special numeric encoding inside plug-in settings.
|
||||
- An internal compatibility change remains fail-closed for replication, but it no longer destroys the person's synchronisation preferences.
|
||||
- A new installation has no previous internal-version marker and therefore does not show an upgrade review. Its initial settings and onboarding remain responsible for keeping replication disabled until configuration is complete.
|
||||
- An older installation cannot dismiss evidence that a newer implementation or settings schema has already been used on the device.
|
||||
- The Obsidian-specific dialogue depends only on a host-neutral compatibility result and the injected confirmation capability. Commonlib remains responsible for settings migration, device-local storage, and the replication gate.
|
||||
- A future incompatible database change must increment `VER`, provide an actionable review message, verify the remote version negotiation, and test both the pending and acknowledged states. A major SemVer increase without those changes has no database-compatibility effect.
|
||||
|
||||
## Verification
|
||||
|
||||
- Unit tests verify new-Vault initialisation, upgrades, missing and invalid markers, downgrades, future settings schemas, legacy marker migration, acknowledgement ordering, and save-failure recovery while retaining automatic synchronisation choices.
|
||||
- Unit tests verify that a pending review is honoured by the packaged Commonlib replication service before remote activity begins.
|
||||
- A real-Obsidian settings test verifies the dedicated summary and details dialogues, captures representative screenshots, confirms that the acknowledged internal version advances only after explicit resume, and confirms that the Change Log contains no acknowledgement control.
|
||||
@@ -1,4 +1,5 @@
|
||||
# Data Structures of Self-Hosted LiveSync
|
||||
|
||||
## Overview
|
||||
|
||||
Self-hosted LiveSync uses the following types of documents:
|
||||
@@ -30,7 +31,7 @@ export interface DatabaseEntry {
|
||||
This document stores version information for Self-hosted LiveSync.
|
||||
The ID is fixed as `obsydian_livesync_version` [VERSIONING_DOCID]. Yes, the typo has become a curse.
|
||||
When Self-hosted LiveSync detects changes to this document via Replication, it reads the version information and checks compatibility.
|
||||
In that case, if there are major changes, synchronisation may be stopped.
|
||||
This internal database version is independent of the plug-in's SemVer version. The last version explicitly acknowledged on a device is stored through Commonlib's device-local configuration contract. When that version differs, or when a settings migration requires review, Self-hosted LiveSync presents a dedicated compatibility dialogue and blocks replication without changing the user's automatic synchronisation choices. A supported upgrade can resume only after explicit review. A downgrade from a newer acknowledged database version, or settings written by a future schema, remains blocked until a compatible plug-in is installed.
|
||||
Please refer to negotiation.ts.
|
||||
|
||||
### Synchronise Information Document
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
+9
-5
@@ -21,7 +21,9 @@ There are many settings in Self-hosted LiveSync. This document describes each se
|
||||
|
||||
## 0. Change Log
|
||||
|
||||
This pane shows version up information. You can check what has been changed in recent versions.
|
||||
This pane always shows the current release history. It does not track whether a particular plug-in version has been read and does not open automatically after an ordinary update.
|
||||
|
||||
Internal database or settings compatibility reviews use a separate safety dialogue, not this pane. The dialogue explains why remote synchronisation has been paused and preserves the automatic synchronisation choices which were configured before the update. Closing it keeps synchronisation paused. When the detected state can be handled by the running version, the explicit resume action records the current internal database version and restores the configured behaviour. A persistent Notice and the `Review why synchronisation is paused` command reopen the review. An older installation cannot dismiss a pause caused by a newer database or settings version.
|
||||
|
||||
## 1. Setup
|
||||
|
||||
@@ -170,7 +172,7 @@ The active remote server type. This is automatically projected to the legacy con
|
||||
|
||||
Setting key: notifyThresholdOfRemoteStorageSize
|
||||
|
||||
MB (0 to disable). We can get a notification when the estimated remote storage size exceeds this value.
|
||||
MB (0 to disable). At startup, Self-hosted LiveSync shows a long-lived, clickable notice when this value has not been configured or the estimated remote storage size exceeds it. Select **Review options** to open the detailed, untimed dialogue. Running the remote-size check explicitly opens that dialogue directly.
|
||||
|
||||
### 3. Privacy & Encryption
|
||||
|
||||
@@ -197,6 +199,7 @@ In default, the path of the file is not obfuscated to improve the performance. I
|
||||
Setting key: E2EEAlgorithm
|
||||
|
||||
The encryption algorithm version used for end-to-end encryption.
|
||||
|
||||
- `v2` (V2: AES-256-GCM With HKDF): Recommended and default version.
|
||||
- `forceV1` or `""` (V1: Legacy): Older legacy encryption. Only use this if you have an existing vault encrypted in the legacy format.
|
||||
|
||||
@@ -447,6 +450,7 @@ Apply preset configuration
|
||||
Setting key: syncMode
|
||||
|
||||
The trigger mechanism for synchronisation.
|
||||
|
||||
- **LiveSync** (`LIVESYNC`): Real-time, continuous, bidirectional synchronisation.
|
||||
Note: This requires a CouchDB or WebRTC P2P remote server. It is not supported for S3-compatible Object Storage.
|
||||
- **Periodic Sync** (`PERIODIC`): Synchronisation is performed at regular intervals specified by the **Periodic Sync interval** setting.
|
||||
@@ -748,11 +752,11 @@ Setting key: concurrencyOfReadChunksOnline
|
||||
|
||||
Setting key: minimumIntervalOfReadChunksOnline
|
||||
|
||||
#### Maximum size of chunks to send in one request
|
||||
#### Maximum request size for manually resending chunks
|
||||
|
||||
Setting key: sendChunksBulkMaxSize
|
||||
|
||||
Limit the maximum size of chunks to send in a single bulk request (MB).
|
||||
Limit the maximum size of chunks sent in one request by the explicit **Resend all chunks** maintenance operation (MB). Ordinary and initial replication do not use this setting.
|
||||
|
||||
## 9. Power users (Power User)
|
||||
|
||||
@@ -938,7 +942,7 @@ Disables all synchronisation and restart.
|
||||
|
||||
#### Resend
|
||||
|
||||
Resend all chunks to the remote.
|
||||
Explicitly resend all locally available chunks to the remote. This is a recovery and maintenance operation; ordinary replication does not pre-send every chunk.
|
||||
|
||||
#### Reset journal received history
|
||||
|
||||
|
||||
Reference in New Issue
Block a user