contentful-import 10.4.0 → 10.5.1

package/README.md

@@ -282,7 +282,8 @@ The data to import should be structured like this:
   "experienceTemplates": [],
   "dataAssemblies": [],
   "experienceFragments": [],
-  "experiences": []
+  "experiences": [],
+  "releases": []
 }
 ```
 
@@ -290,6 +291,8 @@ Note: `tags` are not available for all users. If you do not have access to this
 
 The `designTokens`, `components`, `experienceTemplates`, `dataAssemblies`, `experienceFragments`, and `experiences` keys are Experience Orchestration (ExO) entities — see the "Experience Orchestration (ExO) entities" section below.
 
+The `releases` key is subject to the [Releases](https://www.contentful.com/help/releases/) feature — see the "Releases" section below.
+
 ## :test_tube: Experience Orchestration (ExO) entities
 
 > **Experimental:** ExO entities (`designTokens`, `components`, `experienceTemplates`, `dataAssemblies`, `experienceFragments`, `experiences`) are `@internal` and considered experimental. Their shape and import behavior are subject to change without notice.
@@ -348,6 +351,18 @@ Two behaviors are worth calling out explicitly because they differ from every ot
 - Export files taken before the ExO entity rename (`ComponentType` → `Component`, `Fragment` → `ExperienceFragment`, `Template` → `ExperienceTemplate`) are upgraded automatically on import, including the corresponding resource-link `linkType`s and URN path segments. This upgrade is upgrade-only (there's no downgrade path) and idempotent, so it's safe to run against already-upgraded data.
 - Export files that predate ExO entirely (no ExO keys, or empty ExO arrays) import unchanged — no extra configuration is needed to import older export files.
 
+## :package: Releases
+
+> **Only `Release.v2` ("Releases") is supported. `Release.v1` ("Launch") is not supported.**
+>
+> **The destination space's organization must have the [Releases](https://www.contentful.com/help/releases/) entitlement enabled.** Releases is a premium/paid feature — if the destination isn't entitled, importing releases will fail.
+
+If your source content includes a `releases` key, each entry is checked for `sys.schemaVersion`. Only releases with `sys.schemaVersion: "Release.v2"` are imported; any `Release.v1` (Launch) release is skipped and logged as an error, since its payload shape isn't compatible with the `Release.v2` create/update API.
+
+A release that already exists in the destination space at the source's exact `sys.id` is updated; otherwise one is created. There is no separate publish/unpublish step for releases — a release's own `entities` collection already carries the per-entity `publish`/`unpublish` action to take when the release itself is applied.
+
+**Releases have no ID-preserving create, unlike every other importable entity.** The Releases API always server-generates a release's `sys.id` on create — there is no way to request a specific ID. So the update path above only fires if a release already exists in the destination at the source's exact ID (for example, an environment cloned from the source) — which an import run can never produce on its own. Practically: re-importing the same source data creates additional releases rather than updating the ones from a prior run. If you need to re-run an import that includes releases, delete or archive the previously-imported ones first to avoid duplicates.
+
 ## :bulb: Importing to a space with existing content
 
 - Both source space and destination space must share the same content model structure. In order to achieve that, please use [contentful-migration](https://www.npmjs.com/package/contentful-migration).
@@ -368,6 +383,7 @@ Two behaviors are worth calling out explicitly because they differ from every ot
 - Imported webhooks with credentials will be imported as normal webhooks. Credentials should be added manually afterwards.
 - Imported webhooks with secret headers will be imported without these headers. Secret headers should be added manuall afterwards.
 - If you have custom UI extensions, you need to reinstall them manually in the new space.
+- `Release.v1` ("Launch") releases are not supported for import — only `Release.v2` ("Releases") releases are imported; see the "Releases" section above.
 - Per-locale publish state is restored, with three caveats:
   - The destination has to support [locale-based publishing](https://www.contentful.com/help/localization/locale-based-publishing/), which means two things: the organization is entitled to it (it is not on every plan), and the destination environment has "Locale-based (un)publishing" selected under **Settings > Locales > Publishing options** — the default is "Publish all locales". The import checks the entitlement up front and detects an environment that publishes whole entities anyway, and in either case logs a warning and falls back to publishing every locale, exactly as it did before this feature. The import itself does not fail.
   - A locale that was `changed` in the source space (published, with newer draft edits on top) is imported as `published`. Reconstructing `changed` needs two separate writes, which an import cannot express.