docs: improve the v4 release notes (#782)

website/docs/releases/migration-4.md

@@ -1,201 +1,171 @@
-# Migration guide from 3.x to 4.x
+# Crowdin CLI v4
 
-This guide is intended to help you migrate from CLI 3.x to 4.x. It is not a comprehensive guide, but rather a list of the most important changes.
+This guide is intended to highlight the most important changes in Crowdin CLI v4 and help you migrate from CLI v3 with ease. It is not a comprehensive guide, but rather a list of the most important changes.
 
-### Glossary updates
+:::tip
+Need help or have questions? [Let's discuss it](https://github.com/crowdin/crowdin-cli/discussions/781)!
+:::
 
-* removed `name` prop from upload and download commands
-* moved `id` to arguments (only for download commands)
-* updated `list` cmd output
+## Command updates
 
-Before:
+### Init
 
-- `crowdin glossary download --id <id>` or `crowdin glossary download --name <name>`
-- `crowdin glossary upload --id <id>` or `crowdin glossary upload --name <name>`
+The `generate` alias has been removed:
 
-After:
+```diff
+-crowdin generate
++crowdin init
+```
 
-(Use `list` command to get id)
-
-- `crowdin glossary download <id>`
-- `crowdin glossary upload --id <id>`
-
-### TM updates
-
-* removed `name` prop from upload and download commands
-* moved `id` to arguments (only for download commands)
-* updated `list` cmd output
-
-Before:
-
-- `crowdin tm download --id <id>` or `crowdin tm download --name <name>`
-- `crowdin tm upload --id <id>` or `crowdin tm upload --name <name>`
+### Lint
 
-After:
+The `lint` command has been replaced with the [`config lint`](/commands/crowdin-config-lint) command.
 
-(Use `list` command to get id)
+```diff
+- crowdin lint
++ crowdin config lint
+```
 
-- `crowdin tm download <id>`
-- `crowdin tm upload --id <id>`
+### Pre-translate
 
-### Screenshots updates
+We've made significant changes to the [`pre-translate`](/commands/crowdin-pre-translate) command. The command now requires the `file` parameter for file-based projects. The `file` parameter determines which files to pre-translate. Previously, the command relied on the current configuration, and it was only possible to pre-translate the files that matched the configuration patterns. Now you can specify any file(s) in the Crowdin project to pre-translate.
 
-* updated `list`, `upload` cmd output
-* replaced `name` parameter with `id` to `delete` cmd
+Tip: Use the [`file list`](/commands/crowdin-file-list) command to get the file paths in the current project.
 
-Before:
+### Branch
 
-- `crowdin screenshot delete <name>`
+The `list branches` command has been replaced with the [`branch list`](/commands/crowdin-branch-list) command:
 
-After:
+```diff
+-crowdin list branches
++crowdin branch list
+```
 
-(Use `list` command to get id)
+### File
 
-- `crowdin screenshot delete <id>`
+* The `list project` command has been replaced with the [`file list`](/commands/crowdin-file-list) command.
+* Added verbose (`--verbose`) output.
+* Added a possibility to download translations for all project languages (`-l all`).
 
-### Branch updates
+```diff
+-crowdin list project
++crowdin file list
+```
 
-* removed `crowdin list branches` command
-* create new command `crowdin branch list` command
-* updated `list`, `add` cmd output
+### String
 
-Before:
+* Added the `--branch` parameter support instead of specifying a branch in the file path in the `add` command.
+* The [`string edit`](/commands/crowdin-string-edit) command changes:
+  * moved `id` to parameter
+  * now `identifier` is used as an option to edit and not to find the needed string.
+* The [`string delete`](/commands/crowdin-string-delete) command changes:
+  * moved `id` to parameter. Now only 1 string can be removed at a time
+  * removed `text` and `identifier` options. Only `id` is used as a string identifier.
+* Added `--directory` and `--scope` options to the [`string list`](/commands/crowdin-string-list) command.
 
-- `crowdin list branches`
+```diff
+-crowdin string add Download --file main/src/strings.xml --identifier "download"
++crowdin string add Download --file src/strings.xml --branch main --identifier "download"
+```
 
-After:
+```diff
+-crowdin string edit --id 12 --text new
++crowdin string edit 12 --text new
+```
 
-- `crowdin branch list`
+```diff
+-crowdin string delete --id 12
++crowdin string delete 12
+```
 
-### Language updates
+### Language
 
-* removed `crowdin list languages` command
-* create new command `crowdin language list` command
-* updated `list` cmd output
-* added new param `--all` to get all languages for current account
-* changed default `code` for list command. Now it's `id` instead of `two_letters_code`
+* The `list languages` command has been replaced with the [`language list`](/commands/crowdin-language-list) command.
+* Changed default `code` for list command. Now it's `id` instead of `two_letters_code`. It's more convenient since the `id` is used for the `--language` parameter in various commands.
+* Added a new parameter `--all` which allows to list all languages for the current account.
 
-Before:
+```diff
+-crowdin list languages
++crowdin language list
+```
 
-- `crowdin list languages`
+### List
 
-After:
+* The `list sources` command has been replaced with the [`config sources`](/commands/crowdin-config-sources) command.
+* The `list translations` command has been replaced with the [`config translations`](/commands/crowdin-config-translations) command.
 
-- `crowdin language list`
-- 
-### File updates
+```diff
+-crowdin list sources
++crowdin config sources
+```
 
-* removed `crowdin list project` command
-* create new command `crowdin file list` command
-* updated `list`, `upload` cmd output
-* added verbose (`--verbose`) output
-* to download translations for all project languages `-l all` can be used
+```diff
+-crowdin list translations
++crowdin config translations
+```
 
-Before:
+With this change, it's now clearer that these commands will output the local sources and translations that match patterns in the configuration file.
 
-- `crowdin list project`
+### Glossary
 
-After:
+The `name` property has been removed from the `upload` and `download` commands:
 
-- `crowdin file list`
+```diff
+-crowdin glossary download --id <id>
+-crowdin glossary download --name <name>
++crowdin glossary download <id>
+```
 
-### Init command
+```diff
+-crowdin glossary upload <file> --name <name>
++crowdin glossary upload <file> --id <id>
+```
 
-* `generate` alias was removed
+Tip: Use the [`list`](/commands/crowdin-glossary-list) command to get the `id`.
 
-Before:
+### TM
 
-- `crowdin init` or `crowdin generate`
+The `name` property has been removed from `upload` and `download` commands:
 
-After:
+```diff
+-crowdin tm download --id <id>
+-crowdin tm download --name <name>
++crowdin tm download <id>
+```
 
-- `crowdin init`
+```diff
+-crowdin tm upload <file> --name <name>
++crowdin tm upload <file> --id <id>
+```
 
-### String updates
+Tip: Use the [`list`](/commands/crowdin-tm-list) command to get the `id`.
 
-* in `add` command added `branch` param support instead of branch in file path
-* `edit` command rework
-  * moved `id` to parameter
-  * now `identifier` is used as an option to edit and not to find needed string
-  * output updates
-* `delete` command rework
-  * moved `id` to parameter. Now only 1 string can be removed at time
-  * removed `text` and `identifier` options. Only `id` is used as a string identifier
-  * output updates
-* in `list` command added `--directory` and `--scope` options. Output updates
-* `add`, `comment` cmd output update 
+### Screenshot
 
-Before:
+The `name` parameter has been replaced with the `id` for the `delete` command because there can be multiple screenshots with the same name:
 
-- `crowdin string add Download --file main/src/values/strings.xml --identifier "app.download"`
-- `crowdin string edit --id 12 --text new`
-- `crowdin string delete --id 12`
+```diff
+-crowdin screenshot delete <name>
++crowdin screenshot delete <id>
+```
 
-After:
+Tip: Use the [`list`](/commands/crowdin-screenshot-list) command to get the `id`.
 
-- `crowdin string add Download --file src/values/strings.xml --identifier "app.download" --branch main`
-- `crowdin string edit 12 --text new`
-- `crowdin string delete 12`
+## Deprecations and backward compatibility
 
 ### Download targets
 
-* removed `crowdin download targets` command
-* removed `targets` from configuration file
-
-### Pre-translate
-
-* added `file` parameter (required for file-based projects)
-* now `file` value(s) determines which files to pre-translate
-
-### Task updates
-
-* updated `add` cmd output
-* removed backward compatibility for file ids in task add command
-
-### Crowdin List => Crowdin Config
-
-* renamed `crowdin list` to `crowdin config`
-* `sources`, `translations` cmd output update
-
-Before:
-
-- `crowdin list sources`
-- `crowdin list translations`
--
-After:
-
-- `crowdin config sources`
-- `crowdin config translations`
-
-### Lint
-
-* command was moved under `config` namespace
-* `lint` command output update
-
-Before:
-
-- `crowdin lint`
-
-After:
-
-- `crowdin config lint`
-
-### Bundle
-
-* updated `list`, `add` cmd output
-
-### Comment
-
-* updated `list` cmd output
-
-### Distribution
+The deprecated `download targets` command has been removed. The configuration file no longer supports the `targets` section as well. Use [Bundles](/commands/crowdin-bundle) instead.
 
-* updated `add` cmd output
+### Task command
 
-### Label
+Removed backward compatibility for file numeric id in the [`task add`](/commands/crowdin-task-add) command. Now only file path is supported:
 
-* updated `add` cmd output
+```diff
+-crowdin task add --file 12 --language uk
++crowdin task add --file src/strings.xml --language uk
+```
 
-### Other
+## Command output updates
 
-* success messages updates
+In this release, we've also reviewed and improved the output of many commands to make them more informative and user-friendly. Changes include `list`, `add`, `upload`, `download`, `delete`, and other commands for various resources.

website/docusaurus.config.js

@@ -84,6 +84,13 @@ const config = {
           }
         ],
       },
+      announcementBar: {
+        id: "cli_v4",
+        content:
+          '🎉 <a target="_blank" rel="noopener noreferrer" href="/crowdin-cli/releases/migration-4">Crowdin CLI v4</a> is out! 🥳',
+        backgroundColor: "#029e87",
+        textColor: "#ffffff",
+      },
       footer: {
         style: 'dark',
         links: [