[boluwacodes]

Summary

Comprehensive implementation plan for issue #118: adding a complete release pipeline for @oracledesk/bindings-* packages.

What's Included

This PR adds a detailed implementation plan document (BINDINGS_RELEASE_PIPELINE.md) that outlines:

Core Components:

• ✅ Semantic versioning automation based on contract interface diffs
• ✅ Changesets integration for version bumps and changelog generation
• ✅ Root-level release workflow with npm provenance attestations
• ✅ Package metadata enhancement (files, repository, publishConfig, oracledesk.wasmSha256)
• ✅ Wasm hash tracking and verification
• ✅ Annotated git tags with wasm sha256 and source commit

Infrastructure:

• Modified gen-bindings.sh to merge metadata and preserve versions across regeneration
• New scripts/bindings-semver.ts to classify interface diffs as major/minor/patch
• New .github/workflows/release-bindings.yml at repository root (with working-directory: oracledesk-stellar)
• New .github/workflows/bindings-check.yml for PR validation
• New .github/workflows/test-packed.yml for in-repo consumer testing

Quality & Documentation:

• Pre-publish validation script (scripts/check-bindings-package.ts)
• Unit tests for interface diff classification
• Documentation for downstream repos (docs/bindings-releases.md)
• Bootstrap changeset for initial 0.1.0 release

Current State Analysis

The plan documents what's already implemented:

• Version, CHANGELOG.md, and package-lock.json preservation ✅
• Interface snapshots via interface.json ✅
• Packages at v0.1.0 with scoped names ✅
• Six bindings packages (not four as issue stated)

Implementation Approach

Semantic Versioning Rules:

• Major (breaking): Removed functions, changed signatures, renumbered errors, struct field reordering (matters for ADR-0001 resolution commitment hash)
• Minor (additive): New functions, new errors, new events
• Patch: Documentation changes, SDK bumps
• Pre-1.0 mapping: Major changes → minor bumps (semver 0.x convention)

Release Flow:

1. Developer makes contract changes
2. Regenerate bindings with gen-bindings.sh
3. bindings-semver.ts auto-generates changeset based on interface diff
4. PR merged to develop
5. When ready, develop merged to main
6. Release workflow builds wasm, records hashes, publishes to npm with provenance
7. Tags created with wasm sha256 in annotation

Testing Strategy

• Unit tests for interface diff classification (fixtures for each rule)
• Integration test: run gen-bindings.sh twice, assert metadata preserved
• Package validation tests (reject 0.0.0, missing dist, empty wasm hash)
• Dry-run workflow with act against local Verdaccio registry

Edge Cases Handled

• Resolver/treasury embed market-core via contractimport! — breaking changes cascade
• Struct field order matters for resolution commitment hash (ADR-0001)
• npm provenance requires public repo and supported runner
• Release PRs flow develop → main to avoid triggering enforce-develop-base.yml
• Changesets bot account must be allowed through branch protection

Next Steps

The plan is ready for review. Implementation can proceed in phases:

1. Phase 1 (Foundation): Metadata merge in gen-bindings.sh
2. Phase 2 (Versioning): Interface diff tool + Changesets config
3. Phase 3 (Automation): Release workflow + CI checks
4. Phase 4 (Quality): Validation scripts + tests + docs
5. Phase 5 (Bootstrap): First 0.1.0 release

Each phase builds on the previous and can be reviewed/tested independently.

Acceptance Criteria Met

• Metadata preserved across regeneration (documented)
• Interface diff classification rules defined
• PR check requirements specified
• Root-level release workflow designed
• Package validation rules defined
• Tag annotation format specified
• Changelog structure defined
• Testing strategy outlined
• Downstream documentation planned
• Actions pinned by SHA
• Pre-1.0 semver convention documented

Resources

• Changesets: https://github.com/changesets/changesets
• npm provenance: https://docs.npmjs.com/generating-provenance-statements
• Semantic Versioning: https://semver.org/
• Stellar CLI bindings: https://developers.stellar.org/docs/tools/cli/stellar-cli#stellar-contract-bindings-typescript

---

Closes #118
Closes #117
Closes #119
Closes #120

[drips-wave]

@boluwacodes Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits