Skip to content

feat: establish Nx migrations foundations#928

Open
nx-plugin-for-aws wants to merge 1 commit into
mainfrom
feat/migrations-foundations
Open

feat: establish Nx migrations foundations#928
nx-plugin-for-aws wants to merge 1 commit into
mainfrom
feat/migrations-foundations

Conversation

@nx-plugin-for-aws

@nx-plugin-for-aws nx-plugin-for-aws commented Jul 11, 2026

Copy link
Copy Markdown
Collaborator

Reason for this change

First step of the Nx Migrations workstream for v1.0 (#718): before any migration can ship, the plugin needs migrations.json wired in, a versioning mechanism compatible with the repo's tag-only release model, and documented contributor guidelines. Strategy discussed and locked in on #703 (deterministic vs agentic split per Nx 23's agentic nx migrate).

Description of changes

  • Wire migrations.json into packages/nx-plugin/package.json via the nx-migrations field, and copy it into dist as a compile asset. The collection starts empty — no released change currently warrants a migration (the feat(ts#mcp-server): stop vending a nested project package.json #916 nested package.json removal leaves a harmless leftover in existing workspaces, which per the strategy is not a migration).
  • Version stamping at package time (scripts/stamp-migrations.ts, new stamp-migrations target in the package dependency chain). Source migrations.json entries carry no version field — the release model never commits versions to source. The script derives them from git release tags:
    • a migration present in a previous tag keeps the version of the earliest tag registering it (never re-runs for users already past that release);
    • an unshipped migration is stamped strictly between the latest tag and any possible next release (e.g. 1.0.0-rc.321.0.0-rc.32.1), so it runs for every user upgrading from any released version regardless of what the next release number turns out to be. Semver precedence comparison is implemented in utils/migration-versions.ts (git tag sort isn't semver-aware for prereleases).
  • Contributing guide: new Migrations section in CONTRIBUTING.md covering the three Nx 23 migration kinds (deterministic implementation / agentic prompt / hybrid), what should and shouldn't be a migration, guardrails, versioning, and testing expectations.

Description of how you validated changes

  • Unit tests for the stamping logic (semver comparison incl. rc-tag edge cases, shipped/unshipped stamping, field preservation).
  • Ran the full package target: stamped dist migrations.json produced correctly against the current tag set (empty collection passes through cleanly).
  • Full test suite green via pre-commit.

Issue # (if applicable)

Closes #703.

Checklist


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@codecov-commenter

codecov-commenter commented Jul 11, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 85.71429% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.70%. Comparing base (fe10023) to head (4b6b4a7).
⚠️ Report is 11 commits behind head on main.

Files with missing lines Patch % Lines
packages/nx-plugin/src/utils/migration-versions.ts 85.71% 2 Missing and 4 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #928      +/-   ##
==========================================
+ Coverage   87.61%   87.70%   +0.09%     
==========================================
  Files         156      158       +2     
  Lines        5723     5830     +107     
  Branches     1363     1393      +30     
==========================================
+ Hits         5014     5113      +99     
- Misses        362      364       +2     
- Partials      347      353       +6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Wire migrations support into @aws/nx-plugin per the strategy in #703:

- Register migrations.json via the package.json nx-migrations field
- Stamp migration versions at package time from git release tags
  (scripts/stamp-migrations.ts): shipped migrations keep the version of
  the first tag registering them; unshipped migrations get a version
  strictly between the latest tag and any possible next release, so
  contributors never author version fields
- Document the migrations strategy in CONTRIBUTING.md: the three Nx 23
  migration kinds (deterministic / agentic prompt / hybrid), what
  should and shouldn't be a migration, guardrails, versioning and
  testing expectations

Closes #703
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Define Nx migrations strategy and contributing guidelines

2 participants