From 109bc0bf53da6fe2bc169a7bb6dc42c098b8512e Mon Sep 17 00:00:00 2001 From: alvarosabu Date: Tue, 24 Mar 2026 11:03:40 +0100 Subject: [PATCH] Update content versioning guide to clarify terminology and processes --- content/guides/01.data-model/1.collections.md | 4 +-- .../guides/02.content/6.content-versioning.md | 32 +++++++++---------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/content/guides/01.data-model/1.collections.md b/content/guides/01.data-model/1.collections.md index 98a1e4f9..c0176324 100644 --- a/content/guides/01.data-model/1.collections.md +++ b/content/guides/01.data-model/1.collections.md @@ -66,7 +66,7 @@ Once a collection is created, there are a number of configuration options availa Content versioning is used by :product-link{product="editor"} and allows teams to create and manage different versions of their content. There are several reasons to use content versioning, including drafting content without publishing it, and more ways to collaborate with others. -This feature can be enabled for specific collections, and will be available for all items. Once enabled, item versions can be created, and later have some or all fields promoted to the main version, typically used for publishing. +This feature can be enabled for specific collections, and will be available for all items. Once enabled, item versions can be created, and later have some or all fields published to the main version. ::callout{icon="material-symbols:menu-book-outline" color="primary" to="/guides/content/content-versioning"} Read the content versioning user guide. @@ -76,7 +76,7 @@ Read the content versioning user guide. Live preview is used by :product-link{product="editor"} and allows for your application to be shown in a pane next to your content, which can be used for previewing content before publishing. -You can use item field values to construct the URL used by the live preview, including unique identifiers and content version, allowing for previewing content versions before promoting them to the main version. +You can use item field values to construct the URL used by the live preview, including unique identifiers and content version, allowing for previewing content versions before publishing them to the main version. ::callout{icon="material-symbols:school-outline" color="secondary" to="/tutorials/getting-started"} Read tutorials on implementing live preview. diff --git a/content/guides/02.content/6.content-versioning.md b/content/guides/02.content/6.content-versioning.md index 13edc969..8bdd9057 100644 --- a/content/guides/02.content/6.content-versioning.md +++ b/content/guides/02.content/6.content-versioning.md @@ -10,10 +10,10 @@ use content versioning, including drafting content without publishing it, and mo ## Concepts -- **Version**: A version of an item that allows you to safely make changes without affecting the published item. Versions can be promoted to become the new published item. +- **Version**: A version of an item that allows you to safely make changes without affecting the published item. Versions can be published to become the new published item. - **Published**: The published version of your content that is live and visible to users. All new versions are created from the published item. This version is identified by the reserved key `published` (the key `main` also works and is kept for backward compatibility). - **Draft**: a reserved global version that is automatically available when content versioning is enabled. The draft version provides a dedicated workspace for making changes before publishing, and appears empty until edits are saved. -- **Promote**: when a version is promoted, it becomes the published item that is displayed to users. +- **Publish**: when a version is published, it becomes the published item that is displayed to users. - **Revision**: revisions are individual changes to items made within a version or the published item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state. ::callout{icon="material-symbols:info-outline" to="/guides/content/live-preview"} @@ -71,15 +71,15 @@ Fill in your fields and save as normal. On first save, Directus creates a draft You can save as many times as needed. Required fields do not need to be complete at this stage - see [Making Changes to a Version](#making-changes-to-a-version). -### Publishing via Promote +### Publishing an Itemless Draft -When you are ready to publish, select **"Promote Version"** from the version dropdown. Because there is no existing item to compare against, Directus skips the comparison modal and creates the item directly. +When you are ready to publish, select **"Publish Version"** from the version dropdown. Because there is no existing item to compare against, Directus skips the comparison modal and creates the item directly. -After promotion, you are redirected to the newly created item in its main version. +After publishing, you are redirected to the newly created item in its main version. ::callout{icon="material-symbols:info-outline"} **Permissions** -Promoting an itemless draft creates a new item, so it requires **create** permission on the collection - not edit permission. +Publishing an itemless draft creates a new item, so it requires **create** permission on the collection - not edit permission. :: ## Creating a New Version @@ -103,20 +103,20 @@ Upon saving the changes, you'll notice that the main item remains unaffected, wh ::callout{icon="material-symbols:info-outline"} **Required Fields** -Versions can be saved even if required fields are empty. Validation of required fields is deferred to promote time, so you can save partial drafts without completing all required fields. +Versions can be saved even if required fields are empty. Validation of required fields is deferred to publish time, so you can save partial drafts without completing all required fields. :: -## Comparing and Promoting a Version +## Comparing and Publishing a Version -![Promoting a version, comparing its changes](/img/versions-example-comparison.png) +![Publishing a version, comparing its changes](/img/versions-example-comparison.png) -Promoting a version makes it the published (current) version of your content. +Publishing a version makes it the published (current) version of your content. -### How to Promote a Version +### How to Publish a Version -1. Open the version you want to promote -2. Select the **"Promote Version"** option from the dropdown. +1. Open the version you want to publish +2. Select the **"Publish Version"** option from the dropdown. ::callout{icon="material-symbols:warning"} **Required Field Validation** @@ -127,11 +127,11 @@ If the version has missing required fields, Directus will display field-level va - Fields with differences from the published item are highlighted with color indicators - Review each highlighted field to understand what will change 4. Accept or reject individual changes as needed -5. Click **"Promote"** to finalize and make this version the new main item. +5. Click **"Publish"** to finalize and make this version the new main item. -Once promoted, this version becomes the active content, and the previous published item is preserved in the version history. +Once published, this version becomes the active content, and the previous published item is preserved in the version history. -After promoting a version, you can choose to keep or delete the version. For the global draft version, you'll see options to "Discard Edits" or "Keep Edits" instead of "Delete Version" or "Keep Version". +After publishing a version, you can choose to keep or delete the version. For the global draft version, you'll see options to "Discard Edits" or "Keep Edits" instead of "Delete Version" or "Keep Version". ::callout{icon="material-symbols:info-outline"} **Programmatically Implement Content Versioning**