Merge #391: docs(changeset): Add section on version compatibility

80c962b docs(changeset): Add section on version compatibility (valued mammal)
e9bd912 fix(changeset): Add serde(default) attribute to locked_outpoints field (valued mammal)

Pull request description:

  ### Description

  Partially addresses #234 by improving the documentation of `ChangeSet` by adding a version compatibility policy, clarifying what upgrade/downgrade paths are supported and how breaking changes should be handled. It also adds the `#[serde(default)]` attribute to `locked_outpoints` which is a newly added field in 3.0.

  In summary the policy says:

  - Changes to the `ChangeSet` data structure will correspond to a major version bump.
  - Version N can read/deserialize data written by N-1, i.e., one major version back, but this guarantee doesn't extend to version N-2 or earlier.
  - New fields introduced in version N must implement `Default` so that when deserializing, any missing fields are filled in with the default.
  - Version N-1 can deserialize version N data by ignoring unknown fields, with the caveat that not all features from version N will be available.
  - Outline a 3-version deprecation cycle

  ### Changelog notice

  Changed

  - Added `#[serde(default)]` to `ChangeSet::locked_outpoints`

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)

ACKs for top commit:
  luisschwab:
    ACK 80c962b
  oleonardolima:
    ACK 80c962b

Tree-SHA512: dec7197750ccbffaf3c8f99a82d8c9be40a88eb27c73b7fd33b07afe5af1e0d3496ed0a55efa2bcf3486ececfb44b25413bb3cbd40905fe9b2f76b6f938e8f2e

Author: ValuedMammal

src/wallet/changeset.rs

@@ -76,12 +76,42 @@ type IndexedTxGraphChangeSet =
 ///
 /// Existing fields may be extended in the future with additional sub-fields. New top-level fields
 /// are likely to be added as new features and core components are implemented. Existing fields may
-/// be removed in future versions of the library.
+/// be removed in future versions of the library following the deprecation policy below.
 ///
-/// The authors reserve the right to make breaking changes to the [`ChangeSet`] structure in
-/// a major version release. API changes affecting the types of data persisted will display
-/// prominently in the release notes. Users are advised to look for such changes and update their
-/// application accordingly.
+/// ## Version Compatibility
+///
+/// Any change to the [`ChangeSet`] data structure MUST correlate with a major version bump per
+/// [Semantic Versioning]. We guarantee that version N can read and
+/// deserialize [`ChangeSet`] data written by version N-1 (one major version back), but this
+/// guarantee does NOT extend to version N-2 or earlier. New fields added in version N must
+/// implement [`Default`] so that when reading N-1 data, absent fields are populated with default
+/// values.
+///
+/// Limited forward compatibility is provided for downgrades: version N-1 will successfully
+/// deserialize version N data without errors by ignoring unknown fields. Users should be aware that
+/// features introduced in version N will not be available when downgrading to N-1, and that
+/// downgrading can result in loss of data if not backed up. For this reason we recommend carefully
+/// planning major upgrades and backing up necessary data to avoid compatibility issues.
+///
+/// Fields can be removed using a 3-version deprecation cycle: fields are marked deprecated in
+/// version N with a reason and instructions for migrating, the field is retained in version N+1
+/// for compatibility where it deserializes but may not be used, and finally removed in version
+/// N+2. This ensures the standard backwards compatibility guarantees while allowing the removal of
+/// deprecated fields.
+///
+/// ### Responsibilities
+///
+/// Library authors SHOULD test all upgrade paths using the persistence test suite and in CI.
+/// Library authors MUST document API changes prominently in the release notes and CHANGELOG,
+/// clearly mark deprecated fields including migration instructions, and follow the 3-version
+/// deprecation cycle before removing fields.
+///
+/// Users SHOULD back up wallet data before major version upgrades, test upgrades in non-production
+/// environments first, and monitor the release notes for warnings and updates. Users MUST complete
+/// migrations within the compatibility window, and not skip major versions (i.e. upgrade major
+/// versions sequentially).
+///
+/// ### Custom Persistence Implementations
 ///
 /// The resulting interface is designed to give the user more control of what to persist and when
 /// to persist it. Custom implementations should consider and account for the possibility of
@@ -102,6 +132,7 @@ type IndexedTxGraphChangeSet =
 /// [`WalletPersister`]: crate::WalletPersister
 /// [`Wallet::staged`]: crate::Wallet::staged
 /// [`Wallet`]: crate::Wallet
+/// [Semantic Versioning]: <https://doc.rust-lang.org/cargo/reference/semver.html>
 #[derive(Default, Debug, Clone, PartialEq, Deserialize, Serialize)]
 pub struct ChangeSet {
     /// Descriptor for recipient addresses.
@@ -117,6 +148,7 @@ pub struct ChangeSet {
     /// Changes to [`KeychainTxOutIndex`](keychain_txout::KeychainTxOutIndex).
     pub indexer: keychain_txout::ChangeSet,
     /// Changes to locked outpoints.
+    #[serde(default)]
     pub locked_outpoints: locked_outpoints::ChangeSet,
 }