Upgrade Guide

DAML Package Upgrade Guide

Quick reference for upgrading DAML packages in this repository.

Quick Commands

Major Version Upgrade (v07 → v08)

npm run upgrade-package -- --package Subscriptions --type major

Minor Version Upgrade (0.0.1 → 0.0.2)

npm run upgrade-package -- --package Subscriptions --type minor

What Gets Changed

Major Upgrade

• ✅ Folder renamed (e.g., OpenCapTable-v33/ → OpenCapTable-v34/)
• ✅ Package name updated in daml.yaml
• ✅ Version reset to 0.0.1 in daml.yaml
• ✅ All file references updated across the repository
• ✅ multi-package.yaml updated

Minor Upgrade

• ✅ Version incremented in daml.yaml (e.g., 0.0.1 → 0.0.2)
• ✅ All version references updated across the repository

Available Packages

Current packages that can be upgraded (see root multi-package.yaml for the full set):

• OpenCapTable → OpenCapTable-v34
• OpenCapTableReports → OpenCapTableReports-v01
• OpenCapTableProofOfOwnership → OpenCapTableProofOfOwnership-v01
• NftApi → NftApi-v01
• NftReference → NftReference-v01
• EquityCertificate → EquityCertificate-v01
• EquityCertificateShared (no -vNN folder suffix)
• Subscriptions (alias for CantonPayments folder)
• CouponMinter
• Shared (no version suffix)

Test is a dependent package (not typically version-bumped like the libraries above).

Workflow

1. Run the upgrade script:

   npm run upgrade-package -- --package <name> --type <major|minor>

2. Review the changes:

   git status
   git diff

3. Build and test:

   npm run build && npm run test

4. Commit the changes:

   git add -A
   git commit -m "Upgrade <package> to <new-version>"

Examples

Example 1: Major Upgrade

# Before: CantonPayments (version 0.2.3)
npm run upgrade-package -- --package Subscriptions --type major
# After: CantonPayments (version 0.0.1)

Files changed:

• CantonPayments/ → CantonPayments/
• CantonPayments/daml.yaml (name and version fields)
• multi-package.yaml
• All scripts referencing CantonPayments
• README files
• Test files

Example 2: Minor Upgrade

# Before: CantonPayments (version 0.2.3)
npm run upgrade-package -- --package Subscriptions --type minor
# After: CantonPayments (version 0.2.4)

Files changed:

• CantonPayments/daml.yaml (version field only)
• Any files with hardcoded version strings

Script Details

See scripts/README.md for full documentation of the upgrade script.

Notes

• The script skips node_modules, .daml, lib, and generated directories
• The script validates folder and version formats before making changes
• Review all changes with git diff before committing