Releases (#1920)

* WIP

* Create first draft of Releases documentation

* Remove a completed TODO item

* WIP

* Add future flag

* Improvements

* Add missing features docs link

* Fix table

* Adjust for alpha release + add real screenshots

* Fix SEO and add badges

* Make final adjustments to intro.

* Clean up future flag documentation

* Make a few more adjustments

* Fix permissions

* Fix link

* Remove Cloud Pro badges

* Add pricing information to Cloud table

* Make feature/future flag adjustments

* Fix object in feature flag docs

* Fix sidebar label for features config.

* Fix wording

* Fix procedure list numbers

* Remove experimental callout and include information in intro.

* Mention future flags in User Guide introduction

* Update docusaurus/docs/user-docs/releases/managing-a-release.md

Co-authored-by: markkaylor <[email protected]>

* Update docusaurus/docs/user-docs/releases/creating-a-release.md

Co-authored-by: markkaylor <[email protected]>

* Update docusaurus/docs/user-docs/content-manager/adding-content-to-releases.md

Co-authored-by: markkaylor <[email protected]>

* Update docusaurus/docs/dev-docs/configurations/features.md

Co-authored-by: Josh <[email protected]>

* More improvements

No time for a proper commit message, sorry 😂

* Update Future badge style

* Update badges order

We'll remove the Alpha, then the Future badge first.

* Fix SEO tags

* Fix & → and

* Use SVG icon for "more" button

* Remove Cloud Pro badge from CM docs

* Remove updated badge on Writing Content

---------

Co-authored-by: markkaylor <[email protected]>
Co-authored-by: Josh <[email protected]>

docusaurus/docs/cloud/getting-started/usage-billing.md

@@ -18,6 +18,7 @@ The usage-based pricing for Strapi Cloud is based on the following criteria and
 | **Assets Bandwidth** | 100GB | 500GB | 1,000GB |
 | **API Requests** | 10,000 | 1,000,000 | 2,000,000 |
 | **Audit Logs** | 7 days retention | N/A | 7 days retention |
+| **Releases** | 3 pending releases | N/A | 3 pending releases |
 
 Where:
 
@@ -26,6 +27,7 @@ Where:
 - **Assets Storage** is the amount of storage used by your assets.
 - **Assets Bandwidth** is the amount of bandwidth used by your assets. 
 - **API Requests** are the number of requests made to your APIs. This includes requests made to the GraphQL and REST APIs.
+- **Releases** are the maximum number of pending [releases](/user-docs/releases/introduction) that can be created.
 
 ## Seats management
 
@@ -83,4 +85,4 @@ If you don't pay the invoice, the subscription of your project will automaticall
 
 #### Project suspension for other reasons
 
-If your project was suspended for reasons other than unpaid invoice leading to subscription cancellation, you may not have the possibility to reactivate your project yourself. You should receive an email with instructions on how to resolve the issue. If you do not receive the email notification, please contact [Strapi Support](mailto:[email protected]).
+If your project was suspended for reasons other than unpaid invoice leading to subscription cancellation, you may not have the possibility to reactivate your project yourself. You should receive an email with instructions on how to resolve the issue. If you do not receive the email notification, please contact [Strapi Support](mailto:[email protected]).

docusaurus/docs/dev-docs/configurations.md

@@ -43,6 +43,7 @@ Some specific features require additional configuration:
 | [Cron jobs](/dev-docs/configurations/cron) | <ul><li>In the `/config/server` file to enable the feature</li><li>In a dedicated, optional `cron-tasks` file that can be used to declare the jobs</li></ul> | Required to setup CRON jobs for the server. |
 | [Environment variables](/dev-docs/configurations/environment) | In dedicated files and folders for the environment (e.g., `config/env/production/server`) | Optionally used to define different environments and their variables. |
 | [Single Sign-On (SSO)](/dev-docs/configurations/sso) <EnterpriseBadge /> | In the `config/admin` file | Required to use the Entreprise-only SSO feature if enabled on your project. |
+| [Feature flags](/dev-docs/configurations/features) | In the `config/features` file | Optional for a typical, stable Strapi application.<br/>Only required to enable [future flags](/dev-docs/configurations/features).|
 
 ## Guides
 

docusaurus/docs/dev-docs/configurations/features.md

@@ -0,0 +1,109 @@
+---
+title: Features configuration
+sidebar_label: Features
+description: Enable experimental Strapi features
+displayed_sidebar: devDocsConfigSidebar
+---
+
+# Features configuration
+
+The `config/features.js|ts` file is used to enable feature flags. Currently this file only includes a `future` object used to enable experimental features through **future flags**.
+
+Some incoming Strapi features are not yet ready to be shipped to all users, but Strapi still offers community users the opportunity to provide early feedback on these new features or changes. With these experimental features, developers have the flexibility to choose and integrate new features and changes into their Strapi applications as they become available in the current major version as well as assist us in shaping these new features.
+
+Such experimental features are indicated by a <FutureBadge /> badge throughout the documentation and enabling these features requires enabling the corresponding future flags. Future flags differ from features that are in alpha in that future flags are disabled by default.
+
+:::danger
+Enable future flags at your own risk. Experimental features may be subject to change or removal, may contain breaking changes, may be unstable or not fully ready for use, and some parts may still be under development or using mock data.
+:::
+
+<!-- ! Commented out as not relevant for now -->
+<!-- Future flags can also be utilized for enabling coming breaking changes in upcoming versions (when prefixed by `vX`, with 'X' being the target version). In this scenario, if you decide to enable a future flag for a breaking change, you will need to migrate your application to adapt to this breaking change. The benefit of this approach however, is that changes can be adopted incrementally as opposed to one large migration when the next major release occurs. Some of these flags may have started out as regular unstable but development showed the need for breaking changes. Finally, the aim of this is to empower developers to be able to smoothly transition to new major versions without the need to modify their existing application code where possible. -->
+
+## Enabling a future flag
+
+To enable a future flag:
+
+1. (_optional_) If the server is running, stop it with `Ctrl-C`.
+2. Open the `config/features.js|ts` file or create it if the file does not exist yet. The file will export a `future` object with all the future flags to enable.
+3. To enable a future flag, add its property name (see [full list](#available-future-flags)) to the `future` object and ensure the property's value is set to `true`. The following example shows how to enable the `contentReleases` future flag:
+
+  <Tabs groupId='js-ts'>
+
+  <Tab value="js" label="JavaScript">
+
+  ```ts title="/config/features.ts"
+  module.export = ({ env }) => ({
+    future: {
+      // You could also simply write: contentReleases: true
+      contentReleases: env.bool('STRAPI_FEATURES_FUTURE_CONTENT_RELEASES', false),
+    },
+  })
+
+  ```
+
+  This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line:
+
+  ```json title=".env"
+  STRAPI_FEATURES_FUTURE_CONTENT_RELEASES=true
+  ```
+
+  If your environment file does not include this value, the `contentReleases` future flag property value  will default to `false` and the experimental feature will not be enabled.
+
+  </Tab>
+
+  <Tab value="ts" label="TypeScript">
+
+  ```ts title="/config/features.ts"
+  export default {
+    future: {
+      // You could also simply write: contentReleases: true
+      contentReleases: env.bool('STRAPI_FEATURES_FUTURE_CONTENT_RELEASES', false),
+    },
+  };
+  ```
+
+  This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line:
+
+  ```json title=".env"
+  STRAPI_FEATURES_FUTURE_CONTENT_RELEASES=true
+  ```
+
+  If your environment file does not include this value, the `contentReleases` future flag property value will default to `false` and the experimental feature will not be enabled.
+
+  </Tab>
+  </Tabs> 
+
+4. Rebuild the admin panel and restart the server:
+
+  <Tabs groupId="yarn-npm">
+  <Tab value="yarn" label="Yarn">
+
+    ```sh
+      yarn develop
+    ```
+  </Tab>
+  <Tab value="npm" label="NPM">
+
+    ```sh
+      npm run develop
+    ```
+
+  </Tab>
+  </Tabs>
+
+## Future flags API
+
+Developers can use the following APIs to interact with future flags:
+
+- Features configuration is part of the `config` object and can be read with `strapi.config.get('features')` or with `strapi.features.config`.
+
+- `strapi.features.future` returns the `isEnabled()` that can be used to determine if a future flag is enabled, using the following method: `strapi.features.future.isEnabled('featureName')`.
+
+## Available future flags
+
+The following future flags are currently available and can be used in the `future` object of the `config/features` configuration file:
+
+| Property name     | Related feature                              | Suggested environment variable name       |
+| ----------------- | -------------------------------------------- | ----------------------------------------- |
+| `contentReleases` | [Releases](/user-docs/releases/introduction) | `STRAPI_FEATURES_FUTURE_CONTENT_RELEASES` |

docusaurus/docs/user-docs/content-manager/adding-content-to-releases.md

@@ -0,0 +1,62 @@
+---
+title: Including content in a release
+description: Instructions to include content in a release
+displayed_sidebar: userDocsSidebar
+---
+
+# Including content in a release  <EnterpriseBadge /> <CloudTeamBadge /> <FutureBadge /> <AlphaBadge />
+
+Using the [Releases](/user-docs/releases/introduction) feature, you can group several entries to publish them altogether. Adding entries to a release is done from the Content Manager. You can also remove an entry from a release while updating the entry.
+
+:::prerequisites
+- Before entries can be added to a release, you must create a release from the [Releases](/user-docs/releases/creating-a-release) page.
+- Adding content to a release requires the appropriate permissions for the Content-Releases plugin (see [configuring administrator roles](/user-docs/users-roles-permissions/configuring-administrator-roles#plugins-and-settings)).
+:::
+
+<!-- TODO: re-add when implemented -->
+<!-- ## Adding multiple entries to a release
+
+Multiple entries can be added to a [release](/user-docs/releases/introduction) from the list view of the Content Manager.
+
+To add entries to a release:
+
+1. From the list view of the Content Manager, select which entries you want to add by ticking the box on the left side of the entries' record.
+2. Click on the **Add to release** button located above the header of the table.
+3. Select which release to add these entries to.
+4. Decide whether these entries will be published or unpublished when the release is published, then click **Continue**. -->
+
+<!-- TODO: add screenshot -->
+
+<ThemedImage
+  alt="Including content in a release"
+  sources={{
+    light: '/img/assets/releases/release-cm-edit-view.png',
+    dark: '/img/assets/releases/release-cm-edit-view_DARK.png',
+  }}
+/>
+
+## Adding a single entry to a release
+
+An entry can be added to a [release](/user-docs/releases/introduction) while editing it from the edit view of the Content Manager.
+
+To add an entry to a release:
+
+1. In the Releases box in the right sidebar, click the **+ Add to release** button.
+2. Select which release to add this entry to.
+3. Decide whether the entry will be published or unpublished when the release itself is published, then click **Continue**.
+
+## Removing a single entry from a release
+
+An entry can be removed from a [release](/user-docs/releases/introduction) while editing it from the edit view of the Content Manager.
+
+To remove an entry from a release:
+
+1. In the Releases box in the right sidebar, click the **…** three dots below the name of the release.
+2. Click the **Remove from release** button.
+
+<!-- TODO: re-add when implemented -->
+<!-- :::tip
+You can also remove multiple entries from a release directly from the release page (see [Managing a release](/user-docs/releases/managing-a-release)).
+::: -->
+
+<!-- TODO: add screenshot -->

docusaurus/docs/user-docs/intro.md

@@ -23,6 +23,8 @@ Before going any further into this user guide, we recommend you to acknowledge t
 
 - **License and Pricing Plans** <br/> As a Strapi user you have the choice between using the Community Edition, which is entirely free, or the [Enterprise Edition](https://strapi.io/pricing-self-hosted). In this user guide, if a feature is only available for the Enterprise Edition, an <EnterpriseBadge /> badge is displayed beside the section's title.
 
+- **Future flags** <br/> Some incoming Strapi features are not yet ready to be shipped to all users, but Strapi still  offers community users the opportunity to provide early feedback on these new features or changes. This feedback is invaluable in enhancing the feature before the final release. Such experimental features are indicated by a <FutureBadge /> badge throughout the documentation and enabling these features requires enabling the corresponding future flags (see [Developer Docs](/dev-docs/configurations/features#enabling-a-future-flag)).
+
 - **Roles and Permissions** <br/> Some features of the admin panel, as well as the content managed with Strapi itself, are ruled by a system of permissions. From your Strapi admin panel, you have the possibility to define, at a detailed level, the roles and permissions of all administrators and end users. In this user guide, all features and possible options are documented. It is however possible, depending on your role and permissions, that you may not be able to access all these features and options. In that case, please refer to the main Super Admin of your Strapi application.
 
 With all this in mind, you should be ready to start your Strapi experience!

docusaurus/docs/user-docs/releases/creating-a-release.md

@@ -0,0 +1,34 @@
+---
+title: Creating a release
+description: Instructions to create a release from the admin panel
+---
+
+# Creating a release  <EnterpriseBadge /> <CloudTeamBadge /> <FutureBadge /> <AlphaBadge />
+
+The [Releases](/user-docs/releases/introduction) page allows creating new releases that will be used to organize entries.
+
+<!-- TODO: add actual screenshots for both light and dark modes -->
+<ThemedImage
+  alt="Adding a new release"
+  sources={{
+    light: '/img/assets/releases/new-release.png',
+    dark: '/img/assets/releases/new-release_DARK.png',
+  }}
+/>
+
+<br /><br />
+
+To create a new release:
+
+1. Click the **+ New Release** button in the upper right corner of the Releases page.  
+2. Give the release a name.
+3. Click the **Continue** button.
+
+Adding entries to a release must be done from the Content Manager. You can add a single entry to a release while creating or editing the entry [in the edit view](/user-docs/content-manager/adding-content-to-releases).
+
+<!-- TODO: for later, when multiple addition is implemented -->
+<!-- 
+Adding entries to a release must be done from the Content Manager:
+
+- You can add multiple entries to a release [from the list view](/user-docs/content-manager/adding-content-to-releases#adding-multiple-entries-to-a-release).
+- You can also add a single entry to a release while creating or editing the entry [in the edit view](/user-docs/content-manager/adding-content-to-releases#adding-a-single-entry-to-a-release). -->

docusaurus/docs/user-docs/releases/introduction.md

@@ -0,0 +1,34 @@
+---
+title: Introduction to Releases
+description: Introduction to the Releases feature that enables content managers to organize entries to publish/unpublish simultaneously
+---
+
+# Releases <EnterpriseBadge /> <CloudTeamBadge/> <FutureBadge /> <AlphaBadge/>
+
+Releases enables content managers to organize entries into containers that can perform publish and unpublish actions simultaneously. A release can contain entries from different content types and can mix locales.
+<!-- TODO: comment out once it's available — grouping is not available with the alpha release -->
+<!-- Entries can be grouped by content type or locale, facilitating review and editing before publication. -->
+
+Releases is currently only available as an experimental feature. To enable it, set the appropriate future flag. See <a href="/dev-docs/configurations/features">future flags</a> documentation for instructions on how to enable a future flag.
+
+<ThemedImage
+  alt="List of Releases"
+  sources={{
+    light: '/img/assets/releases/releases-overview.png',
+    dark: '/img/assets/releases/releases-overview_DARK.png',
+  }}
+/>
+
+<!-- TODO: update Releases icon with the neutral version -->
+Administrators can access Releases from ![Releases icon](/img/assets/icons/releases.svg) _Releases_ in the main navigation of the admin panel.
+
+From the Releases view, it is possible to:
+
+<!-- TODO: add numbers to reflect screenshot -->
+- [create a new release](/user-docs/releases/creating-a-release)
+- view pending and done releases
+- click on a release to [manage its content](/user-docs/releases/managing-a-release)
+
+:::info
+It's not currently possible to schedule the publication of a release, so releases should be published manually. Automatic scheduling will be added in a future version of Strapi.
+:::

docusaurus/docs/user-docs/releases/managing-a-release.md

@@ -0,0 +1,68 @@
+---
+title: Managing a release
+description: Instructions on how to manage a Release from the admin panel
+---
+
+# Managing a release <EnterpriseBadge /> <CloudTeamBadge /> <FutureBadge />  <AlphaBadge />
+
+Adding entries to a [release](/user-docs/releases/introduction) allow viewing them altogether on a single page.
+
+<!-- TODO: add actual screenshots for both light and dark modes -->
+<ThemedImage
+  alt="Release details"
+  sources={{
+    light: '/img/assets/releases/release-details.png',
+    dark: '/img/assets/releases/release-details_DARK.png',
+  }}
+/>
+
+<br /><br />
+
+From a release page, you can:
+
+- edit the name of the release, or delete the release,
+<!-- - [adjust the view](#choose-how-entries-are-grouped) to display entries grouped either by locale or by content-type, -->
+- decide whether an entry will be published or unpublished with the release,
+<!-- - edit a specific entry or [remove](#remove-entries-from-a-release) it from the release, -->
+- and publish the release.
+
+## Editing a release
+
+You can rename a release. To do so, while on a release page:
+
+1. Click on the ![More icon](/img/assets/icons/more.svg) button in the top right corner of the admin panel.
+2. Select ![Edit icon](/img/assets/icons/edit.svg) **Edit**.
+3. In the modal, change the name of the release in the _Name_ field.
+4. Click **Continue** to save the change.
+
+<!-- TODO: re-add when implemented -->
+<!-- ## Choose how entries are grouped
+
+A release page can display entries either grouped by locales or by content-type. To change how entries are grouped, click the **Group by …** dropdown and select an option from the list. -->
+
+<!-- TODO: add screenshot? -->
+
+## Publish or unpublish entries
+
+A release includes multiple entries. You can set the state of each entry with the **Publish** and **Unpublish** action buttons. When the release itself is “published” then the desired actions will be simultaneously performed on each entry.
+
+<!-- TODO: re-add when implemented -->
+<!-- ## Remove entries from a release
+
+Entries can be removed from a release. To do so, click the three dots **…** at the end of the line of an entry and select the **Remove from release** button. -->
+
+## Publishing a release
+
+Publishing a release means that all the actions (publish or unpublish) defined for each entry included in the release will be performed simultaneously. To publish a release, click the **Publish** button in the top right corner of the admin panel.
+
+:::caution
+Once a release is published, the release itself cannot be updated. You can not re-release that specific release with the same group of entries with some modifications; you must create another release.
+:::
+
+## Deleting a release
+
+You can delete a release. Deleting a release will only delete the release itself, but not the content-type entries included in the release. To delete a release, while on the release page:
+
+1. Click on the ![More icon](/img/assets/icons/more.svg) button in the top right corner of the admin panel.
+2. Select ![Delete icon](/img/assets/icons/delete.svg) **Delete**.
+3. In the confirmation dialog, click ![Delete icon](/img/assets/icons/delete.svg) **Confirm**.