Migration Guides

This section provides migration guides for upgrading between TrustWeave versions and understanding deprecation policies.

Version Compatibility Matrix

TrustWeave Version Kotlin Java Gradle Status
1.0.0-SNAPSHOT 2.2.0+ 21+ 8.5+ Current

Deprecation Policy

TrustWeave follows semantic versioning (SemVer) principles:

  • Major versions (X.0.0): Breaking changes allowed
  • Minor versions (0.X.0): New features, backward compatible
  • Patch versions (0.0.X): Bug fixes only

Deprecation Timeline

  • Deprecation Announcement: Deprecated APIs are marked with @Deprecated annotation and documented in CHANGELOG
  • Minimum Deprecation Period: 6 months before removal
  • Removal: Deprecated APIs are removed in the next major version

How to Handle Deprecations

  1. Check CHANGELOG: Review deprecation notices in CHANGELOG.md
  2. Update Code: Replace deprecated APIs with recommended alternatives
  3. Test Thoroughly: Ensure your code works with new APIs
  4. Plan Migration: Schedule migration before major version upgrade

Migration Guides

Migrating to Phase 4 API (Service Layer Removal)

See Migrating to Phase 4 API for migration from service layer (dids, credentials, wallets) to direct methods:

  • Service layer removal
  • Direct methods migration
  • Error handling updates for sealed results
  • Common migration issues

Migrating to 1.0.0

See Migrating to 1.0.0 for detailed migration instructions covering:

  • Type-safe options migration
  • Result-based API migration
  • Error handling updates
  • Plugin lifecycle changes

Migrating to Typed Values API

See Migrating to Typed Values API for migration from String-based parameters to type-safe typed values:

  • Replacing String parameters with Did, KeyId, etc.
  • Updating DSL builders to use typed values
  • Benefits of compile-time type safety
  • Common migration issues and solutions

Breaking Changes

Breaking changes are clearly marked in the CHANGELOG with migration instructions. Common breaking changes include:

  • API signature changes
  • Return type changes
  • Exception type changes
  • Configuration format changes

Getting Help

If you encounter issues during migration:

  1. Check the FAQ for common questions
  2. Review Error Handling for error patterns
  3. Open an issue on GitHub with migration details
  4. Contact support at www.geoknoesis.com

Table of contents