update-preact

name	update-preact
description	Instructions and guidelines for updating the pinned Preact JS git submodule and synchronizing upstream updates to the Dart preact_signals package.

Updating Preact JS Submodule and preact_signals Package

This guide details the systematic process for updating the pinned Preact.js Signals JS/TS git submodule (third_party/preactjs_signals) and porting its structural updates, algorithmic changes, and optimizations into the Dart preact_signals package.

---

1. Upstream Submodule Management

The upstream JavaScript/TypeScript implementation is tracked via a Git submodule located at third_party/preactjs_signals.

A. Initializing and Synchronizing the Submodule

If the submodule is not initialized, run:

git submodule update --init --recursive

B. Pinned Submodule Version Upgrade

To upgrade the pinned submodule version:

1. Navigate to the submodule directory:

   cd third_party/preactjs_signals
   

2. Fetch all latest upstream branches and tags:

   git fetch --tags origin
   

3. Checkout the desired release tag or commit hash:

   git checkout tags/v1.3.0 # or specific tag/commit hash
   

4. Return to the root workspace directory and stage the updated submodule pointer:

   cd ...
   git add third_party/preactjs_signals
   

---

2. Reviewing Upstream Core Architecture Changes

Once the submodule is checked out to the new version, review the differences inside Preact's TypeScript core codebase:

• Core Primitive File: third_party/preactjs_signals/packages/core/src/index.ts
• Test Suite File: third_party/preactjs_signals/packages/core/test/index.test.ts

Compare changes to locate:

1. Algorithmic Optimizations: Refinements in graph tracking, batch processing, or lazy evaluation cycles.
2. Bug Fixes: Handling of edge-case memory leaks, exception propagates, or subscription-tracking re-entrancy issues.
3. API Contracts: New methods or configuration parameters added to Signal, Computed, or Effect.

---

3. Porting Changes to Dart preact_signals

All ported logic must reside in the packages/preact_signals package.

A. Code Synchronization

Modify the corresponding Dart implementation files to accurately align with the updated Preact JS algorithms:

• Core Signal Primitive: packages/preact_signals/lib/src/signal.dart
• Computed Engine: packages/preact_signals/lib/src/computed.dart
• Effect Engine: packages/preact_signals/lib/src/effect.dart
• Batch Execution: packages/preact_signals/lib/src/batch.dart

[!IMPORTANT] Keep the Dart implementation highly semantic and idiomatic. While replicating Preact's structural logic is necessary to preserve reactive correctness and avoid cycles, leverage Dart's language features (such as late initializers, WeakReference, Expando, or Extension types) appropriately.

B. Porting Upstream Tests

Ensure any new test cases introduced in Preact core's test suite are ported to:

• packages/preact_signals/test/

---

4. Package Release & Changelog Alignment

When changes are ported, increment package versions and document changes.

1. Semantic Versioning: Increase the version in packages/preact_signals/pubspec.yaml based on whether changes are major (breaking changes), minor (features), or patch (bug fixes).
2. Changelog Documentation: Document all changes and the specific upstream version tag synced in packages/preact_signals/CHANGELOG.md.

---

5. Verification Checklist

Execute these verification commands prior to staging code changes:

# 1. Update monorepo dependencies
melos bootstrap

# 2. Run static analysis
melos run analyze

# 3. Format files
dart format .

# 4. Execute all unit tests and verify 100% success
melos run test

# 5. Review combined coverage and verify high metrics
melos run coverage