Migration Adapters
Relevant source files
The following files were used as context for generating this wiki page:
Migration Adapters are a specialized module within the pubm ecosystem designed to facilitate the transition from existing release management tools to pubm. These adapters scan a project's filesystem to detect configurations from supported legacy tools, parse those configurations into a standardized internal representation, and eventually convert them into a pubm.config.ts file.
Sources: packages/core/src/migrate/types.ts, packages/pubm/src/commands/migrate.ts:1-15
The system follows a modular architecture where each supported legacy tool (e.g., semantic-release, np, release-it, changesets) is represented by a dedicated adapter implementing the MigrationSource interface. This allows the core migration pipeline to process different configuration formats through a unified execution flow.
Sources: packages/core/src/migrate/pipeline.ts:15-30, packages/core/src/migrate/adapters/np.ts:133-140
Architecture and Core Interface
The migration system is built around the MigrationSource interface, which defines the contract for any tool-specific adapter.
MigrationSource Interface
Every adapter must implement the following methods:
- detect(cwd): Scans the current working directory for relevant configuration files.
- parse(files, cwd): Loads the identified files and maps them to a
ParsedMigrationConfigobject. - convert(parsed): Transforms the parsed configuration into the final
PubmConfigformat. - getCleanupTargets(detected): Identifies files that can be safely removed after a successful migration.
Sources: packages/core/src/migrate/types.ts:94-101
Data Structure: ParsedMigrationConfig
The system uses an intermediate data structure to normalize settings from various tools before they are written to the final config.
| Field | Type | Description |
|---|---|---|
source | MigrationSourceName | The name of the source tool (e.g., "np", "semantic-release"). |
npm | Object | Publishing settings including publish, access, and tag. |
github | Object | GitHub release settings such as release and draft. |
git | Object | Git settings like branch, tagFormat, and commitMessage. |
hooks | Array | Lifecycle hooks and associated shell commands. |
unmappable | Array | A list of settings that could not be automatically converted. |
Sources: packages/core/src/migrate/types.ts:16-75
Migration Pipeline Flow
The migration process is orchestrated by the executeMigration function. This pipeline manages the lifecycle from parsing to writing the new configuration and cleaning up legacy files.
The diagram shows the sequential steps taken by the core pipeline to transform a legacy project into a pubm-ready project.
Sources: packages/core/src/migrate/pipeline.ts:22-68
Key Pipeline Steps
- Detection: The CLI identifies which adapter should be used based on files like
.releasercorpackage.jsonentries.
Sources: packages/pubm/src/commands/migrate.ts:40-50 - Parsing: Adapters like
nporsemantic-releaseread files (JSON, YAML, or JS) and populate the intermediateParsedMigrationConfig.
Sources: packages/core/src/migrate/adapters/semantic-release.ts:140-160 - CI Advice: The system scans
.github/workflowsfor old release commands (e.g.,npx np) and suggests replacements forpubm.
Sources: packages/core/src/migrate/ci-advisor.ts:20-30 - Cleanup: If requested, standalone legacy configuration files are removed, though
package.jsonis always preserved.
Sources: packages/core/src/migrate/pipeline.ts:63-66
Supported Adapters
Semantic Release Adapter
The semantic-release adapter handles complex configurations involving multiple plugins. It maps common plugins like @semantic-release/npm and @semantic-release/github to pubm equivalents.
- Config Files:
.releaserc,.releaserc.json,.releaserc.yaml,release.config.js, etc. - Logic: It normalizes plugin arrays into a key-value format to extract release branches and asset paths.
Sources: packages/core/src/migrate/adapters/semantic-release.ts:9-30, packages/core/src/migrate/adapters/semantic-release.ts:175-220
NP Adapter
The np adapter focuses on the configuration found in .np-config.json or the np key in package.json.
- Mapping: It directly maps
anyBranch,cleanup(tocleanInstall), andreleaseDraftto pubm properties. - Limitations: Items like
2faandprovenanceare marked as unmappable because they are handled at the npm registry or CLI level rather than via pubm config.
Sources: packages/core/src/migrate/adapters/np.ts:31-40, packages/core/src/migrate/adapters/np.ts:90-110
Changeset Migration
When migrating from changesets, the system performs a filesystem migration of existing changeset markdown files.
The diagram illustrates the specific file movement logic required for the changesets adapter.
Sources: packages/core/src/changeset/migrate.ts:15-50
CI Workflow Integration
The scanCiWorkflows function ensures that CI/CD pipelines are updated to use pubm. It uses regex patterns to find legacy execution strings across various package managers.
| Tool | Search Patterns |
|---|---|
semantic-release | npx semantic-release, yarn semantic-release |
release-it | npx release-it, pnpm release-it |
changesets | changeset publish, changeset version |
np | npx np, yarn np |
Sources: packages/core/src/migrate/ci-advisor.ts:5-18
When a match is found, the pipeline generates "CI Advice" suggesting the replacement of the matched line with npx pubm release:ci.
Sources: packages/core/src/migrate/ci-advisor.ts:40-50
Conclusion
Migration Adapters provide a robust, low-friction path for adopting pubm. By abstracting the differences between tools like np and semantic-release into a unified ParsedMigrationConfig, pubm can automatically generate complex configurations while warning users about unmappable features and necessary CI/CD updates.