feat: create 5.42.0 release notes (#714)

* wip * feat: fully delete cms model * wip * wip * feat: user project upgrade * fix: info about version specific steps * docs: add Full-Screen Editor * refactor: add note about dependency sync * feat: logger * fix: update broken links * fix: update broken links * fix: update deps list * ci:run workflows * fix: update tailwindcss * chore: update next to last possible v12 * fix: update items * fix: remove BCs section * chore: update background task info * fix: logger new table deployment * feat: add update yarn step into upgrade guide * feat: build project after update * fix: remove unnecessary apps from build * feat: api gateway * fix: api gateway * fix: polish changelog * fix: polish changelog * fix: polish changelog --------- Co-authored-by: Bruno Zorić <[email protected]> Co-authored-by: Leonardo Giacone <[email protected]>
webiny · Jan 20, 2025 · d42d37a · d42d37a
1 parent 6e41ca0
commit d42d37a
Show file tree

Hide file tree

Showing 15 changed files with 852 additions and 1,513 deletions.
diff --git a/...e-development-concepts/background-tasks/how-to-handle-a-background-task-run.mdx b/...e-development-concepts/background-tasks/how-to-handle-a-background-task-run.mdx
@@ -102,6 +102,11 @@ const myTask = createTaskDefinition({
 });
 ```
 
+Interface for the response object is defined [here](https://github.com/webiny/webiny-js/blob/84d28b3e100a0317a0c3d265d06efaea50971cd3/packages/tasks/src/response/abstractions/TaskResponse.ts#L62).
+- `message` - optional message you want to store when the task is done
+- `output` - optional output object you want to store when the task is done
+
+
 #### The `continue` Method
 
 This method signalizes that the task has not finished its job and that the Step Function should continue running the Lambda handler.

diff --git a/docs/developer-docs/5.41.x/security/security-framework/api-security.mdx b/docs/developer-docs/5.41.x/security/security-framework/api-security.mdx
@@ -13,17 +13,11 @@ import { Alert } from "@/components/Alert";
 
 </Alert>
 
-<Alert type="info">
-
-If you just want to jump straight into the code, take a look at the [Securing Your Application](/docs/{version}/admin-area/new-app-tutorial/security) tutorials section.
-
-</Alert>
-
 In this article, we cover how Webiny Security Framework (_WSF_ for short) works in the context of Webiny API, what hooks it introduces, and how it hooks into the existing request lifecycle hooks to perform its main tasks (like authentication and authorization).
 
 <Alert type="info">
 
-This article uses terms like authentication, authorization, identity, and permissions extensively. These terms are described in details in the [Introduction](/docs/{version}/core-development-concepts/security-framework/introduction) article. If you're not familiar with these terms, make sure you read that article first.
+This article uses terms like authentication, authorization, identity, and permissions extensively. These terms are described in details in the [Introduction](/docs/{version}/security/security-framework/introduction) article. If you're not familiar with these terms, make sure you read that article first.
 
 </Alert>
 

diff --git a/docs/developer-docs/5.41.x/security/security-framework/react-security.mdx b/docs/developer-docs/5.41.x/security/security-framework/react-security.mdx
@@ -12,15 +12,9 @@ import { Alert } from "@/components/Alert";
 
 </Alert>
 
-<Alert type="info">
-
-If you just want to jump straight into the code, take a look at the [Securing Your Application](/docs/{version}/admin-area/new-app-tutorial/security) tutorials section.
-
-</Alert>
-
 <Alert type="warning" title="Important">
 
-This article is a continuation of the previous two articles about Webiny Security Framework. If you haven't already, please do read the [Introduction](/docs/{version}/core-development-concepts/security-framework/introduction) and [API Security](/docs/{version}/core-development-concepts/security-framework/api-security) articles before continuing.
+This article is a continuation of the previous two articles about Webiny Security Framework. If you haven't already, please do read the [Introduction](/docs/{version}/security/security-framework/introduction) and [API Security](/docs/{version}/security/security-framework/api-security) articles before continuing.
 
 </Alert>
 
@@ -34,7 +28,7 @@ Let's use the following diagram to analyze the order of operations that are goin
 
 Once your application has started, it will render a login form (this can be your custom form or the one provided by your IdP's React SDK). A user submits their credentials to the IdP (`1`). If credentials are valid, IdP will return some basic identity information and a JSON Web Token (JWT) (`2`).
 
-Now that you want to communicate with the Webiny API, you will attach that JWT to every request you make (`3`). The Webiny API will then run the authentication process (`4`) described in the [API Security](/docs/{version}/core-development-concepts/security-framework/api-security) article, and verify the JWT (remember, how you implement your authentication plugin is up to you).
+Now that you want to communicate with the Webiny API, you will attach that JWT to every request you make (`3`). The Webiny API will then run the authentication process (`4`) described in the [API Security](/docs/{version}/security/security-framework/api-security) article, and verify the JWT (remember, how you implement your authentication plugin is up to you).
 
 If the identity is valid and is authorized to perform the requested operation, the React application will receive the expected response from the API.
 

diff --git a/docs/developer-docs/5.42.x/core-development-concepts/basics/logger.mdx b/docs/developer-docs/5.42.x/core-development-concepts/basics/logger.mdx
@@ -0,0 +1,177 @@
+---
+id: t92uhfadjsbfd
+title: Logger
+description: Learn about Logger which we internally use
+---
+
+import {Alert} from "@/components/Alert";
+
+<Alert type="success" title="What you'll learn">
+
+- what is the Logger
+- how to use the Logger
+
+</Alert>
+
+<Alert type="warning">
+  This feature will change in the future. We cannot guarantee the data integrity after the system upgrade (in minor version, eg. 5.42.x to 5.43.0)
+</Alert>
+
+## Overview
+
+Webiny logger is internal feature which we use to log errors and other information into a DynamoDB Log table.
+
+For Logger to work, we deploy a new DynamoDB table called `webiny-logs`.
+
+## How to Use Logger
+
+To use the Logger in your project, you can access it from the Webiny context.
+
+There are multiple levels of logging available:
+  - `debug`
+  - `notice`
+  - `info`
+  - `warn`
+  - `error`
+
+When you want to log something, you can use the following code:
+
+```typescript
+import type {Context} from "./types";
+import {ContextPlugin} from "@webiny/handler-aws";
+
+const myCustomPlugin = new ContextPlugin<Context>(async context => {
+    // some custom code
+    try {
+      await someAsyncFunction();
+    } catch(ex) {
+      const log = context.logger.withSource("where-did-the-log-come-from");
+      // it will log the message with the source "where-did-the-log-come-from"
+      // and the level "error"
+      log.error({
+        message: "Something is wrong with my custom code!",
+        error: ex
+      });
+      // maybe rethrow it?
+      throw ex;
+    }
+});
+```
+
+Note that the `where-did-the-log-come-from` is your custom string, which identifies where the log was created.
+
+This is something you can use to filter logs later.
+
+## How to Access Logger Logs?
+
+There are two ways to access the logs:
+  - directly from the DynamoDB table `webiny-logs`
+  - using the GraphQL API
+
+### DynamoDB Table
+
+You can access the logs directly from the DynamoDB table `webiny-logs`. The table has the following structure:
+
+```ts
+interface Log {
+  id: string;
+  createdOn: string;
+  tenant: string;
+  locale: string;
+  source: string;
+  type: string;
+  // this is the data that was logged - it's always compressed
+  data: {
+    compression: "GZIP",
+    value: string// compressed value
+  };
+}
+```
+
+The data is always compressed using GZIP, so you must decompress it before you can read it.
+
+### GraphQL API
+
+You can also access the logs using the GraphQL API on `/graphql` endpoint. There are multiple queries and mutations available:
+
+ - `listLogs` - to list all logs
+ - `getLog` - to get a single log
+ - `deleteLog` - to delete a single
+ - `deleteLogs` - to delete multiple logs
+ - `pruneLogs` - to delete all logs older than 60 seconds
+
+<Alert type="info">
+
+  For detailed information on how to use the GraphQL API, check out the API Playground in your Webiny Admin UI.
+
+</Alert>
+
+#### List Logs
+
+To list all logs, you can use the `listLogs` query. Here is an example of the query:
+
+```graphql
+query ListLogs {
+  logs {
+    listLogs(
+        where: {
+          tenant: "root",
+          source:"myCustomSource",
+          type: error
+        },
+        sort: DESC,
+        limit: 100,
+        after: "cursorFromPreviousRequest"
+) {
+      data {
+        id
+        type
+        source
+        data
+        createdOn
+      }
+      error {
+        message
+        code
+        data
+        stack
+      }
+      meta {
+        hasMoreItems
+        cursor
+      }
+    }
+  }
+}
+```
+All arguments in `listTags` query are optional.
+
+You can filter the logs by `tenant`, `source` and `type`. Or you can just list all logs, without any filtering applied.
+
+#### Prune Logs
+
+To delete all logs older than 60 seconds, you can use the `pruneLogs` mutation. Here is an example of the mutation:
+
+```graphql
+mutation PruneLogs {
+  logs {
+    pruneLogs {
+      data {
+        task {
+          id
+        }
+      }
+      error {
+        message
+        code
+        data
+        stack
+      }
+    }
+  }
+}
+```
+
+The `pruneLogs` mutation will actually start a background task that will delete the logs. The task ID will be returned in the response, so you can track its progress.
+
+If you try to prune logs while another prune task is running, you will get an error.
diff --git a/...developer-docs/5.42.x/core-development-concepts/basics/user-project-upgrade.mdx b/...developer-docs/5.42.x/core-development-concepts/basics/user-project-upgrade.mdx
@@ -0,0 +1,85 @@
+---
+id: gdkhsbfgiy23
+title: User Project Upgrade
+description: Learn about how to do a project upgrade
+---
+
+import {Alert} from "@/components/Alert";
+
+<Alert type="success" title="What you'll learn">
+
+- what is Webiny project upgrade
+- what are the steps to upgrade a project
+
+</Alert>
+
+## Overview
+
+As a part of our upgrade process, we provide a way to update your codebase on each new release - at least what we can do automatically.
+
+To start the project upgrade use the `yarn webiny upgrade` command.
+
+<Alert type="warning">
+  The upgrade process can only update one minor version at a time. So you can upgrade from 5.40.x to 5.41.x, but not from 5.40.x to 5.42.x.
+</Alert>
+
+## Steps
+
+When a user runs the `yarn webiny upgrade` command, there are multiple steps depending on what are we upgrading in that version.
+
+There might even be some breaking changes, so we need to notify the user about them.
+
+### 1. Notify the User about Breaking Changes
+
+The first step is to notify the user about breaking changes:
+```text
+webiny warning: Note that Webiny 5.xx.x introduces potential breaking changes!
+Before continuing, please review the upgrade guide located at https://webiny.link/upgrade/5.xx.x.
+
+I have read the upgrade guide and I am ready to proceed with the upgrade (y/N):
+```
+
+User needs to press `y` to continue with the upgrade process.
+
+Note that this step will not show if there are no breaking changes in the version user is upgrading to.
+
+### 2. Check User Project Dependency Versions Against the Webiny Dependency Versions
+
+Next step, which will always be executed, is to check if the user project dependencies are in sync with the Webiny dependencies. If they are not, the user will be prompted to update them.
+
+<Alert>
+
+This does not mean that we use newer versions of the dependencies than our users do in their projects.
+
+We ship Webiny with the dependencies that are working with our code. If it is possible, our users should keep their dependencies in sync with Webiny ones to avoid any unexpected problems.
+
+</Alert>
+
+```text
+webiny warning: Found dependencies that are out of sync. Please sync them before continuing with the upgrade process...
+package.json files which have dependencies out of sync:
+ - /packages/apiLib/package.json
+ - /myApp/reactLib/package.json
+
+Dependencies out of sync:
+- react: 17.0.0 (18.2.5)
+- fastify: 4.0.0 (4.2.9)
+
+Do you want us to upgrade those dependencies? (y/N):
+```
+
+User is encouraged to press `y` to update all dependencies in their project.
+
+If user chooses not to upgrade the dependencies, the upgrade process will prompt once more:
+
+```text
+We strongly recommend you update the dependencies.
+Failing to do so may result in unexpected problems.
+Do you still want to continue with the project upgrade and skip updating dependencies? (y/N)
+```
+
+If user chooses to continue without updating the dependencies, the upgrade process will continue, but it is not recommended.
+
+## Version Specific Steps
+
+All steps after the dependency check are specific to the version user is upgrading to.
diff --git a/docs/developer-docs/5.42.x/navigation.tsx b/docs/developer-docs/5.42.x/navigation.tsx
@@ -0,0 +1,21 @@
+import React from "react";
+import { Navigation as BaseNavigation } from "../5.41.x/navigation";
+import { Group, Page, NavigationRoot } from "@webiny/docs-generator";
+
+export const Navigation = () => {
+  return (
+    <>
+      {/* Inherit navigation from 5.41.x. */}
+      <BaseNavigation />
+      {/* Add new items. */}
+      <NavigationRoot directory={__dirname}>
+        <Group title={"Core Development Concepts"}>
+          <Group title={"Basics"} after={"Basics"}>
+            <Page link={"core-development-concepts/basics/user-project-upgrade"} />
+            <Page link={"core-development-concepts/basics/logger"} />
+          </Group>
+        </Group>
+      </NavigationRoot>
+    </>
+  );
+};
diff --git a/docs/release-notes/5.42.0/assets/hcms-fullscreen-editor.gif b/docs/release-notes/5.42.0/assets/hcms-fullscreen-editor.gif