Skip to content

Latest commit

 

History

History
242 lines (151 loc) · 12.1 KB

1160-no-more-release-train.md

File metadata and controls

242 lines (151 loc) · 12.1 KB
stage start-date release-date release-versions teams prs project-link suite
accepted
2026-01-05 00:00:00 UTC
cli
learning
framework
accepted

No Release Train for Blueprints

Summary

Official Ember blueprint packages (app + addon generation) should not be coupled to the Ember / Ember CLI release train. Instead, blueprint packages should be released continuously from the main branch, while ember-cli releases pin (exactly) the blueprint versions they bundle for stability. When generating a new app or addon, ember-cli should prompt to use either the pinned (bundled) blueprint version or the latest available blueprint version—skipping the prompt when both are the same.

Motivation

Ember’s release strategy emphasizes stability and predictability: minor releases approximately every six weeks, Long Term Support (LTS) for 54 weeks, and a commitment to SemVer and backwards compatibility. (See https://emberjs.com/releases/.)

However, default blueprints (what ember new / ember addon generate) have different ergonomics than framework runtime code:

  • Blueprint changes primarily affect newly generated projects, not existing ones.
  • The common social workflow is to propose blueprint improvements via PRs to the default branch.
  • When blueprint improvements are tied to a release train, users can wait weeks (or longer) to see improvements in newly generated apps and addons.

Additionally, while blueprints have historically been used as part of Ember’s upgrade and migration story, that can have an unintended cost for new users: improvements that primarily exist to support long-lived apps and slower-moving upgrade paths can accumulate in the defaults. This can leave new users feeling like they are “paying” for technical debt created by projects that cannot keep up, and that the defaults are holding them back.

We can also think of official blueprints as a product: they are the first experience many users have with Ember, and they encode decisions about tooling, project layout, and “pit of success” defaults. Like any product, we want customers to receive fixes and refinements as quickly as possible.

We want a workflow where blueprint changes can ship as soon as they are merged, while still preserving the stability guarantees that come from Ember CLI releases.

Detailed design

Goals

  • Blueprint packages ship continuously from main.
  • ember-cli defaults to a known-good, pinned blueprint version.
  • Users may choose the latest blueprint version at generation time.
  • Users may specify any specific blueprint version at generation time—interactively via a version selection UI, or non-interactively via --blueprint @blueprint/name@version (e.g. for testing).
  • If pinned and latest match, do not prompt.

Non-goals

  • This does not change Ember’s runtime SemVer or deprecation policies.
  • This does not change existing apps/addons after generation.

Packaging and distribution model

Official blueprints already live in independently versioned npm packages. This RFC proposes changing how those official blueprint packages are released and consumed, not physically relocating the code.

Minimal model:

  • One package for app generation and one for addon generation.
  • Each package is published from main upon merge (or via a release workflow that tracks main), with SemVer versioning.

This RFC intentionally does not prescribe exact package names, but the model assumes:

  • The packages are owned/maintained by the Ember CLI team.
  • Publishing is automated and reproducible.

Official blueprint release process

The release process for official blueprint packages should be decoupled from the ember-cli release train:

  • Merges to main can result in a new blueprint package release (with appropriate SemVer discipline).
  • ember-cli continues to have its own release cadence, and periodically updates the pinned blueprint versions it bundles.

This makes blueprint improvements available to users quickly (via “latest”), without changing the default behavior of any specific ember-cli release.

Pinning for stability

Each ember-cli release must pin to an exact blueprint version for each blueprint package it uses.

In practice, this means the ember-cli package.json uses exact versions (e.g. "1.2.3", not "^1.2.3" or "~1.2.3") for blueprint dependencies.

Rationale:

  • It ensures that ember-cli@X always generates the same output by default.
  • It keeps the “known-good” blueprint version aligned with the ember-cli release QA surface.
  • It avoids accidental behavior changes due to dependency resolution.

Generation-time prompt

When a user runs ember new or ember addon, ember-cli must:

  1. Determine the bundled blueprint version (from its pinned dependency).
  2. Check the registry for the latest blueprint version.
  3. If the versions differ, prompt the user:
  • Use bundled version (recommended): generate with the pinned version.
  • Use latest version: generate with the latest published blueprint version.
  • Choose a specific version: present a version selection UI (e.g. a list of recent published versions from the registry) so the user can pick an exact version.
  1. If the versions are the same, proceed with no prompt.

Prompt text and behavior

The prompt should be explicit about the tradeoff:

  • Bundled: maximizes stability and matches the ember-cli release.
  • Latest: includes the newest blueprint improvements.
  • Specific version: allows the user to pick any published version from a list.

If the registry lookup fails (offline, network errors, etc.), ember-cli should proceed with the bundled version and must not block generation.

Examples

If the bundled blueprint version and latest blueprint version differ:

  • ember new my-app
    • Prompt: Use bundled version (vX.Y.Z, recommended) / Use latest version (vX.Y.Z) / Choose a specific version…

If the user selects "Choose a specific version":

  • ember new my-app → selects "Choose a specific version"
    • Secondary prompt: presents a list of recent published blueprint versions for selection; generation proceeds with the chosen version.

If the bundled blueprint version and latest blueprint version are the same:

  • ember new my-app
    • No prompt; generation proceeds.

If the user is offline or the registry is unavailable:

  • ember new my-app
    • No prompt; generation proceeds using the bundled version.

If the user specifies a specific blueprint version:

  • ember new my-app --blueprint @ember/app-blueprint@1.2.3
    • No prompt; generation proceeds using blueprint version 1.2.3.

Specifying a specific blueprint version

Users can select an exact blueprint version in two ways:

Interactive mode: When the interactive prompt is shown, users may choose "Choose a specific version". ember-cli fetches a list of recent published versions from the registry and presents them as a selectable list. After the user picks a version, generation proceeds with that version and no further prompt is shown.

Note: The interactive version selection UI described here is contingent on out-of-scope work to make blueprint generation generally interactive (i.e. the broader effort to add interactive prompting to ember new/ember addon flows). That work is a prerequisite for this UI and is not defined by this RFC.

Non-interactive mode: Users can pass a version-qualified package specifier to the existing --blueprint flag:

ember new my-app --blueprint @ember/app-blueprint@1.2.3

ember-cli must skip the interactive prompt when a versioned blueprint is explicitly specified this way.

Non-interactive environments

When ember-cli is running in a non-interactive environment (e.g. CI), the default must be bundled to preserve determinism.

This RFC recommends (but does not require) an explicit opt-in flag to avoid relying on interactive prompting in automation:

  • --use-latest-blueprints (or equivalent) to force using the latest blueprint version.

To use a specific blueprint version in automation, use --blueprint @blueprint/name@version (the existing mechanism).

Implementation notes (non-normative)

  • Blueprint packages can be installed into the project being generated (or into a temporary location) and executed similarly to how built-in blueprints work today.
  • Caching the “latest version” check for the duration of a command is acceptable; it must not change the pinned default.

Rollout and work remaining

This RFC describes an end-state, but acknowledges that we have work to do to get there.

In particular, the official app blueprint has historically served both as a “starting point” and as part of the compatibility/upgrade story. The @ember/app-blueprint package only very recently (as of writing this RFC: 6.10-alpha) added a --no-compat option, which is a promising step toward a clearer separation between “new app defaults” and “compatibility scaffolding”, but we should expect incremental iteration before the blueprint defaults and teaching story fully reflect the goals described above.

Compatibility and support expectations

Blueprint packages should follow the same general compatibility expectations as Ember CLI:

  • Changes should be backwards-compatible when feasible.
  • When a breaking change is necessary, it should be done via a SemVer major release of the blueprint package.

Because ember-cli pins versions, breaking blueprint changes only affect users who explicitly choose the latest version (or explicitly opt into the newer major), and will not silently affect users using the bundled version.

Why this simplifies releases

With this design:

  • Blueprint fixes and improvements can ship as soon as they are merged to main (via blueprint package releases).
  • Ember CLI releases no longer serve as the primary vehicle for blueprint delivery; they only select which blueprint versions are bundled.
  • Users who want the newest generator output don’t have to wait 3 months for the next ember-cli release.

How we teach this

Update the Ember CLI documentation and “Creating an app” onboarding path to describe:

  • That ember-cli ships with bundled blueprint versions (stable default).
  • That users may opt into the latest blueprint versions at generation time.
  • What the prompt means, and when they will or won’t see it.

Suggested teaching framing:

  • “Ember’s release train remains the source of stability for runtime behavior.”
  • “Blueprints are project templates: they can evolve faster without affecting existing apps.”
  • “Official blueprints show how you should build a new Ember app or addon today.”

This RFC is intentionally scoped to blueprint release and consumption mechanics. A separate RFC should address the broader product/education distinction between upgrading an existing application and starting a new application, including what guarantees we want to make to each audience.

If this RFC is accepted, we should also document recommended contributor workflow:

  • PRs to blueprint repositories/packages land on main and release continuously.
  • ember-cli periodically updates its pinned blueprint versions.

Drawbacks

  • Pinning a blueprint version in ember-cli means we can't ship bugfixes to the blueprints without an ember-cli release. I think this is a good tradeoff

Alternatives

  • Keep blueprints coupled to ember-cli releases. This preserves the status quo and its complexity and retains the long delay between blueprint improvements and user adoption.
  • Provide a nightly/preview blueprint channel. Adds complexity and still requires decisions about stability vs freshness.
    • We already have workflows in our ecosystem that do "unstable" releases on main, independent of release

Unresolved questions

n/a