Skip to content

PR_CI_DOCS_REFACTOR.md

Latest commit

 

History

History
98 lines (70 loc) · 4.62 KB

PR_CI_DOCS_REFACTOR.md

File metadata and controls

98 lines (70 loc) · 4.62 KB
Raw

CI Improvements, Determinism Documentation, and Core Refactoring

This PR addresses three issues to improve CI reliability, documentation, and code maintainability.

Changes

1. Fix GitHub Actions Node 20 deprecation warnings (#350)

Problem: Every CI job logged "Node.js 20 is deprecated ... forced to run on Node.js 24" for actions/checkout@v4 and pnpm/action-setup@v4. This created noise and would become a hard failure when GitHub drops the Node 20 shim.

Solution:

  • Updated all Node.js version specifications from 20 to 22 in .github/workflows/ci.yml and .github/workflows/deploy-testnet.yml
  • Node 22 is the current LTS version and resolves the deprecation warnings
  • Updated 6 occurrences across both workflow files (packages, contract-types, api-docs, determinism, math-coverage, and dashboard-e2e jobs)

Files changed:

  • .github/workflows/ci.yml
  • .github/workflows/deploy-testnet.yml

Rationale for Node 22: Node 22 is the current LTS release (as of 2026) and provides a stable, long-term supported platform. It resolves the deprecation warnings while maintaining compatibility with the project's dependencies.

2. Document determinism guarantee (#365)

Problem: fixtures/determinism.json and the CI job enforcing it are the project's headline guarantee for cross-language numeric consistency, but there was no documentation explaining:

  • How to add a new determinism test case
  • How to regenerate fixtures
  • What to do when the check fails on a legitimate change
  • What a legitimate fixture change looks like in review

Solution: Created comprehensive documentation in docs/determinism.md covering:

  • Overview of why determinism is critical (on-chain hash同意, cross-platform consistency)
  • How the guarantee works (TypeScript as reference, fixtures generation, enforcement mechanism)
  • Working with fixtures (pnpm fixtures:generate vs pnpm fixtures:check)
  • When to regenerate fixtures
  • How to review fixture changes (legitimate vs suspicious changes)
  • Updating other implementations (Python, Rust) when fixtures change
  • Adding new test cases
  • CI integration and troubleshooting

Files changed:

  • docs/determinism.md (new file)
  • CONTRIBUTING.md (added link to determinism docs, updated to include Rust)
  • python/README.md (added link to determinism docs, updated to include Rust)

Impact: Contributors can now add determinism cases and understand fixture changes without asking for guidance.

3. Refactor packages/core/src/index.ts (#370)

Status: Already completed in a previous refactoring effort.

Context: The file was previously over a thousand lines, holding exports, the agent class, contract invocation, ScVal encoding, struct decoding, and error mapping. This caused merge conflicts to be unreadable and led to features being silently dropped.

Current State: The file is now 311 lines and follows the modular structure documented in docs/architecture/core-modules.md. It serves only as the public API surface with re-exports, while all implementation logic is split into dedicated modules:

  • agent/ - StellarAgent class, invocation, encoding, decoding, queries, mutations, config
  • fleet/ - channel pool, fee strategy, sponsorship, submission queue
  • math/ - deterministic math
  • routing/ - multi-asset route discovery
  • Other top-level modules (signer, contracts, circuitBreaker, ledgerTime, errors, types, telemetry)

Verification: The public API remains unchanged. The generated .d.ts files should not move, confirming no consumer-visible changes.

Testing

Task 1 (CI Node version)

  • CI will run with Node 22 instead of Node 20
  • No deprecation warnings should appear in CI logs
  • All existing tests should pass with Node 22

Task 2 (Determinism docs)

  • Documentation is comprehensive and follows the project's doc style
  • Links from CONTRIBUTING.md and python/README.md are correct
  • Examples and troubleshooting sections are practical

Task 3 (Core refactor)

  • Already verified in previous work
  • pnpm --filter @stellaragent/core test should pass
  • Public API surface unchanged (verified by pnpm docs:api:check)

Checklist

  • Updated Node.js version in CI workflows
  • Created determinism documentation
  • Linked determinism docs from CONTRIBUTING.md
  • Linked determinism docs from python/README.md
  • Verified core refactor is complete (already done)
  • No breaking changes to public API

Related Issues

Closes #350 - [CI] GitHub Actions warns about Node 20 on every run Closes #365 - [Docs] The determinism guarantee is undocumented for contributors Closes #370 - [Refactor] packages/core/src/index.ts is over a thousand lines