中文
devexamples
← Workflows

阅读中文版本

Internal Library Release Workflow

Version and document the internal library, provide a migration guide for breaking changes, publish to the private registry, and announce to internal consumers.

intermediate~90 minreleaseinternal-librariesdx

Objective

Release an internal library so consuming teams can upgrade with clear guidance.

Environment

  • A private package registry
  • Internal communication channels

Steps

1. Version semantically and document the public

Version semantically and document the public surface change.

Expected state: Consumers understand the change.

2. Write a migration guide for any

Write a migration guide for any breaking change.

Expected state: Upgrading has a path.

3. Publish to the private registry

Publish to the private registry with provenance.

Expected state: Consumers can install a trusted build.

4. Announce to consuming teams and track

Announce to consuming teams and track upgrade adoption.

Expected state: Migration is visible.

Decision points

Major bump or a compatible shim?

  • Shim then major
  • Major directly

Offer a compatible shim when many consumers are slow; a direct major break forces simultaneous migration.

Publish from CI or locally?

  • CI with provenance
  • Local

CI with provenance; internal does not mean provenance is optional.

Expected outcome

A versioned internal library published with a migration guide and adoption tracked by consuming teams.

Verification

Confirm the published version installs from the private registry and that consuming teams can complete the migration using the guide.

Cleanup

Record the release and follow up on teams that have not upgraded.

Overview

Release an internal library so consuming teams can upgrade with clear guidance. Confirm the published version installs from the private registry and that consuming teams can complete the migration using the guide.

Steps

  1. Version semantically and document the public surface change. Expected state: Consumers understand the change.
  2. Write a migration guide for any breaking change. Expected state: Upgrading has a path.
  3. Publish to the private registry with provenance. Expected state: Consumers can install a trusted build.
  4. Announce to consuming teams and track upgrade adoption. Expected state: Migration is visible.
npm publish --registry https://npm.internal.example.com
# announce and track adoption in the internal channel

Verification

  • A versioned internal library published with a migration guide and adoption tracked by consuming teams.

Decision points

  • Major bump or a compatible shim? Options: Shim then major; Major directly. Recommended: Offer a compatible shim when many consumers are slow; a direct major break forces simultaneous migration.
  • Publish from CI or locally? Options: CI with provenance; Local. Recommended: CI with provenance; internal does not mean provenance is optional.