From 552e7a2fb699d6b4ed6c98ea83ba69d37656bb75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=82=A8=E3=83=AA=E3=82=B9?= Date: Thu, 6 Mar 2025 15:53:15 +0900 Subject: [PATCH 1/4] doc: refactor platform and plugin version management --- .../platform_plugin_versioning_ref/index.md | 409 ++++++++---------- 1 file changed, 188 insertions(+), 221 deletions(-) diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md index e9c65eeaa7c..bde90ef9e88 100644 --- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md +++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md @@ -24,333 +24,300 @@ description: How to manage platforms & plugins versions. # Version Management -Cordova provides the ability to save and restore platforms and plugins. +Cordova allows developers to **save** and **restore** platforms and plugins, eliminating the need to check in platform and plugin source code. -This feature allows developers to save and restore their app to a known state without having to check in all of the platform and plugin source code. +When a platform or plugin is added, its version details are automatically saved to the `package.json` file. -When adding a platform or plugin, details about the app's platform and plugin versions are automatically saved to the `package.json` file. It is also possible to add a platform or plugin by editing the `package.json` file directly, assuming you know the right tags and syntax. It is not possible to remove plugins or platforms in this manner. The recommended method of adding and removing plugins and platforms is with the Cordova CLI commands `cordova plugin add|remove ...` and `cordova platform add|remove ...` to avoid any out of sync issues. +The recommended way to add or remove platforms and plugins is by using the Cordova CLI commands: -The **restore** step happens automatically when a **`cordova prepare`** is issued, making use of information previously saved in the `package.json` and `config.xml` files. +- `cordova platform add|remove ...` +- `cordova plugin add|remove ...` -One scenario where save/restore capabilities come in handy is in large teams that work on an app, with each team member focusing on a platform or plugin. This feature makes it easier to share the project and reduce the amount of redundant code that is checked in the repository. - -## Platform Versioning - -### Saving Platforms - -To save a platform, issue the following command: - -```bash -cordova platform add ] | directory | git_url> -``` - -After running the above command, the **`package.json`** should update with the platform dependency and cordova related information. - -Example: - -```json -"cordova": { - "platforms": [ - "android" - ] -}, -"dependencies": { - "cordova-android": "^8.0.0", -} -``` - -The `--nosave` flag prevents adding and deleting the specified platform from the `package.json` file. - -Example: - -```bash -cordova platform add ] | directory | git_url> --nosave -``` - -The examples below fetch the package, extract it to `node_modules` and update the `package.json` file accordingly. Under the covers, this process is controlled by the npm CLI. Here are various ways to add platforms. +Using these commands helps prevent out-of-sync issues. -*Adding with Cordova resolved name:* +While it is technically possible to add a platform or plugin by editing `package.json` directly, this is **strongly discouraged**. -Example: +The restore process runs automatically when executing `cordova prepare`, using the information stored in `package.json` and `config.xml`. This applies to both platforms and plugins. If a platform or plugin is defined in both files, `package.json` takes priority. -```bash -cordova platform add android -``` - -The avaialble Cordova resolved names are: +One scenario where save/restore capabilities come in handy is in large teams that work on an app, with each team member focusing on a platform or plugin. This feature makes it easier to share the project and reduce the amount of redundant code that is checked in the repository. -| Cordova Resolved Name | NPM Package Name | -| --- | --- | -| `android` | `cordova-android` | -| `electron` | `cordova-electron` | -| `ios` | `cordova-ios` | -| `browser` | `cordova-browser` | +The adding and removing mechanisim that Cordova CLI uses for platforms and plugins is controlled by npm CLI. Below we will take a look at the command syntax and examples. -*Adding with Cordova resolved name and pinned version:* +## Adding Platforms and Plugins -Example: +**Command Syntax:** ```bash -cordova platform add android@7.1.4 +cordova add [ ...] ``` -This command will explicitly fetch for version `7.1.4`. +The `package-spec` argument supports most formats accepted by the npm CLI. -*Adding with npm package name:* +Examples include: -Example: +- Scoped and non-scoped npm packages +- Local directory paths +- Git remote URLs +- Tarball archives +- [Cordova Resolved Names](#Cordova-Resolved-Names) for official Cordova platforms -```bash -cordova platform add cordova-android -``` +Additionally, the `--nosave` flag could be appended to the command to prevent adding of specified platform and plugins from the `package.json` file. -*Adding with Git URL:* +--- -Example: +**Quick Overview:** -```bash -cordova platform add https://github.com/apache/cordova-android.git -``` +When you add a platform or plugin, `package.json` is updated with its dependencies and Cordova-specific metadata. -or +For example, running the following commands in a Cordova project: ```bash -cordova platform add https://github.com/apache/cordova-android +cordova platform add android@13.0.0 +cordova plugin add cordova-plugin-device@3.0.0 ``` -or +Would result in `package.json` containing the following entries: -```bash -cordova platform add github:apache/cordova-android +```json +"devDependencies": { + "cordova-android": "^13.0.0", + "cordova-plugin-device": "^3.0.0" +}, +"cordova": { + "platforms": [ + "android" + ], + "plugins": { + "cordova-plugin-device": {} + } +} ``` -* **`cordova platform add C:/path/to/android/platform`** - - Retrieves the Android platform from the specified directory, adds it to the project, and updates the `package.json` file. - -* **`cordova platform add android --nosave`** +When restoring a Cordova project, this metadata determines which platforms and plugins will be installed. - Retrieves the pinned version of `cordova-android` platform from npm, adds it to the project, but does not add it to the `package.json` file. +--- -### Updating or Removing Platforms +### Various `add` Examples -It is possible to update and delete a platform from `config.xml` and `package.json`. +- **Cordova Resolved Names for Platforms:** -To update a platform, execute the following command: + ```bash + cordova platform add android + ``` -```bash -cordova platform update ] | directory | git_url> -``` + If no tag or version is specified, the Cordova CLI will fetch the latest release. -To remove a platform, execute one of the following commands: + ```bash + cordova platform add electron@latest + ``` -```bash -cordova platform remove -cordova platform rm -``` + NPM tags are supported and can be appended to the end of the package specification. -Some Examples: + ```bash + cordova platform add ios@7.1.1 + ``` -* **`cordova platform update android`** + Exact release versions published to the npm registry are also supported and can be appended to the end of the package specification. - In addition to updating the `cordova-android` platform to the pinned version, it updates the `package.json` file. +- **npm Package:** -* **`cordova platform update android@3.8.0`** + ```bash + cordova platform add cordova-android + cordova platform add cordova-android@latest + cordova platform add cordova-android@13.0.0 - In addition to updating the `cordova-android` platform to version `3.8.0` it updates the `package.json` file. + cordova platform add @cordova/some-platform + cordova platform add @cordova/some-platform@latest + cordova platform add @cordova/some-platform@1.0.0 -* **`cordova platform update /path/to/android/platform`** + cordova plugin some-cordova-plugin + cordova plugin some-cordova-plugin@latest - In addition to updating the `cordova-android` platform to version found in the provided folder, it updates the `package.json` file. + cordova plugin add @cordova/some-plugin + cordova plugin add @cordova/some-plugin@latest + cordova plugin add @cordova/some-plugin@1.0.0 + ``` -* **`cordova platform remove android`** + Scoped and non-scope npm packages are supported for both platforms and plugins. Optionally, npm package tags or released versions can be targeted by appending to the end of the package name. (e.g. `package-name@latest`). - Removes the `cordova-android` platform from the project and removes it from the `package.json` file. - - _Note: If the platform definition existed in `config.xml` from a previous version of Cordova CLI, it will also be removed from `config.xml`._ + Please note that the scoped packages shown above are only examples and do not exist. -* **`cordova platform remove android --nosave`** +- **Git remote URL:** - Removes the `cordova-android` platform from the project, but does not remove it from the `package.json` file. + ```bash + cordova platform add git://github.com/apache/cordova-android.git + cordova platform add git://github.com/apache/cordova-android.git#feature-branch + cordova platform add git://github.com/apache/cordova-android.git#rel/13.0.0 -### Restoring Platforms + cordova platform add https://github.com/apache/cordova-android.git + cordova platform add https://github.com/apache/cordova-android.git#feature-branch + cordova platform add https://github.com/apache/cordova-android.git#rel/13.0.0 -Platforms are automatically restored from the `package.json` (and `config.xml`) when executing the **`cordova prepare`** command. + cordova platform add https://github.com/apache/cordova-android + cordova platform add https://github.com/apache/cordova-android#feature-branch + cordova platform add https://github.com/apache/cordova-android#rel/13.0.0 + ``` -If a platform is defined in both files, the information defined in `package.json` is used as the source of truth. + Various Git URL formats are supported for installing platforms and plugins. A branch name or tag can be specified by appending `#` to the URL. -After `prepare`, any platforms restored from `config.xml` will update the `package.json` file to reflect the values taken from `config.xml`. + When targeting a branch or tag, ensure it is production-ready before using it in a production environment. This functionality is useful for reviewing pull requests, testing future releases, or submitting in release vote. -If you add a platform without specifying a ``, the version that will be installed is taken from `package.json` or `config.xml`. +- **Git service short hand:** -**If discovered** in both files, `package.json` is given higher priority over `config.xml`. + ```bash + cordova platform add github:apache/cordova-android + cordova platform add github:apache/cordova-android#feature-branch + cordova platform add github:apache/cordova-android#rel/13.0.0 + ``` -Example: + Platforms and plugins can also be checked out from Git repositories using a shorthand format. -Suppose your `config.xml` file contains the following entry: + If your repository is hosted on another Git service, such as Bitbucket or GitLab, you can modify the command to target these services. -```xml - - ... - - ... - -``` + Branches and tags can also be targeted using the shorthand format. However, ensure that the specified branch or version is production-ready before using it in production. -If you run the command **`cordova platform add android`** with no `` specified, the platform `android@7.1.4` will be retrieved and installed. +- **Tarball Archive:** -**Example Order of Priority for Restoring Platforms:** + ```bash + cordova platform add ~/path/to/a/tarbal.tgz + ``` -Suppose you have defined in `config.xml` and `package.json` a platform and version as follows: + Currently, **only platforms** support installation from a tarball package. The supported archive formats are `.tar.gz`, `.tgz,` and `.tar`. -**`config.xml`**: +- **Local Directory Path:** -```xml - -``` + ```bash + cordova platform add ~/path/to/a/cordova-platform + cordova plugin add ~/path/to/a/cordova-plugin -**`package.json`**: + cordova platform add C:/Path/to/a/cordova-platform + cordova plugin add C:/Path/to/a/cordova-plugin + ``` -```json -"cordova": { - "platforms": [ - "android" - ] -}, -"dependencies": { - "cordova-android": "^8.0.0" -} -``` - -When `prepare` is executed, the version from `package.json` has higher priority over `config.xml` and version `^8.0.0` will be installed. - ---- - -## Plugin Versioning + Platforms and plugins can be installed from a local directory path. -The plugin commands are a mirror of the platform commands: +## Removing Platforms and Plugins -### Saving Plugins - -To save a plugin, you issue the following command: +**Command Syntax:** ```bash -cordova plugin add ] | directory | git_url> +cordova remove ``` -After running the above command, the **`package.json`** should contain something as seen below: +The `remove` command also has an alias of `rm`. -```json -"cordova": { - "plugins": { - "cordova-plugin-device": {} - } -}, -"devDependencies": { - "cordova-plugin-device": "^1.0.0" -} -``` +The `package-name` argument must be the name of the platform or plugin you want to remove. -The `--nosave` flag prevents adding and deleting specified plugins from `package.json`. To prevent saving a plugin, you issue the following command: +For platforms, you **MUST** use the [Cordova Resolved Names](#Cordova-Resolved-Names) when removing them. -```bash -cordova plugin add ] | directory | git_url> --nosave -``` +The `--nosave` flag could be appended to the command to prevent removal of specified platform and plugins from the `package.json` file. + +--- -Some Examples: +### Various `remove` Examples -* **`cordova plugin add cordova-plugin-device`** +- **Removing platforms:** - Retrieves the pinned version of the `cordova-plugin-device` plugin from npm, adds it to the project and updates the `package.json` file. + ```bash + cordova platform remove android + ``` -* **`cordova plugin add cordova-plugin-device@2.0.1`** + The above command will remove the `cordova-android` platform from the project and `package.json` file. - Retrieves the `cordova-plugin-device` plugin at version `2.0.1` from npm, adds it to the project and updates the `package.json` file. + _Note: If the platform definition existed in `config.xml` from older version's of Cordova CLI, it will also be removed from `config.xml`._ -* **`cordova plugin add https://github.com/apache/cordova-plugin-device.git`** - - **`cordova plugin add https://github.com/apache/cordova-plugin-device`** - - **`cordova plugin add github:apache/cordova-plugin-device`** +- **Removing plugins:** - npm retrieves the `cordova-plugin-device` plugin from the git repository, adds it to the project and updates the `package.json`. + ```bash + cordova plugin remove cordova-plugin-device + ``` -* **`cordova plugin add C:/path/to/console/plugin`** + The above command will remove the `cordova-plugin-device` plugin from the project and `package.json` file. - Retrieves the `cordova-plugin-device` plugin from the specified directory, adds it to the project, and updates the `package.json` file. + _Note: If the plugin definition existed in `config.xml` from older version's of Cordova CLI, it will also be removed from `config.xml`._ -### Mass Saving of Plugins on an Existing Project +## Updating Platforms -If you have a pre-existing project and you want to save all currently added plugins in the project, you can use: +**Command Syntax:** ```bash -cordova plugin save +cordova platform update [ ...] ``` -### Removing Plugins +You can update platforms using the command above. For details on valid `package-spec` formats, refer to the [Adding Platforms and Plugins](#Adding-Platforms-and-Plugins) section. -It is possible to delete a plugin from `config.xml` and `package.json` with one of the following commands: +_Note: The `update` command applies **only** to platforms._ -```bash -cordova plugin remove -cordova plugin rm -``` +### Various `update` Examples -For Example: +- **Cordova Resolved Name:** -* **`cordova plugin remove cordova-plugin-device`** + ```bash + cordova platform update android + ``` - Removes the `cordova-plugin-device` plugin from the project and deletes its entry from `package.json`. + In addition to updating the `cordova-android` platform to the pinned version, it updates the `package.json` file. - _Note: If the plugin definition existed in `config.xml` from a previous version of Cordova CLI, it will also be removed from `config.xml`._ + ```bash + cordova platform update android@13.0.0 + ``` -### Restoring Plugins + This will update the platform to the targeted version. -Plugins are automatically restored from `package.json` and `config.xml` when executing the **`cordova prepare`** command. +- **Local Directory Path:** -If a plugin is defined in both files, the information defined in `package.json` is used as the source of truth. + ```bash + cordova platform update /path/to/android/platform + ``` -After `prepare`, any plugins restored from `config.xml` will update the `package.json` file to reflect the values taken from `config.xml`. + In addition to updating the `cordova-android` platform to the local directory content, it will also update the `package.json` file pointing to the local directory path. -If you add a plugin without specifying a ``, the version that will be installed is taken from `package.json` or `config.xml`. +### Important Notes on Platform Restoration -**If discovered** in both files, `package.json` is given higher priority over `config.xml`. +1. What version is installed when using `cordova platform add android` and the platform is defined in `config.xml`? -Example: + If the `config.xml` file contains the following entry: -Suppose your `config.xml` file contains the following entry: + ```xml + + ... + + ... + + ``` -```xml - - ... - - ... - -``` + When running the **`cordova platform add android`** command with no version provided, it will use the `spec` version defined in `config.xml`. In this example it would be `13.0.0`. -If you run the command **`cordova plugin add cordova-plugin-device`** with no `` specified, the platform `cordova-plugin-device@2.0.1` will be retrieved and installed. +2. What version is restored if a platform is defined in both `config.xml` and `package.json`? -**Example Order of Priority for Restoring Plugins:** + Suppose your project has the following configurations: -Suppose you have defined in `config.xml` and `package.json` a plugin and version as follows: + **`config.xml`**: -**`config.xml`**: + ```xml + + ``` -```xml - -``` + **`package.json`**: -**`package.json`**: + ```json + "cordova": { + "platforms": [ + "android" + ] + }, + "dependencies": { + "cordova-android": "^13.0.0" + } + ``` -```json -"cordova": { - "plugins": { - "cordova-plugin-splashscreen": {} - } -}, -"devDependencies": { - "cordova-plugin-splashscreen": "1.0.0" -} -``` + When `cordova prepare` is executed, the version from `package.json` has higher priority over `config.xml`. It will install version `^13.0.0`. -When `prepare` is executed, the version from `package.json` has higher priority over `config.xml` and version `1.0.0` will be installed. +## Cordova Resolved Names + +| Cordova Resolved Name | NPM Package Name | + | --- | --- | + | `android` | `cordova-android` | + | `electron` | `cordova-electron` | + | `ios` | `cordova-ios` | + | `browser` | `cordova-browser` | From 9ba63ab6bacbb7bffc45d7b9e27c0d18c0418e61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=82=A8=E3=83=AA=E3=82=B9?= Date: Thu, 6 Mar 2025 16:35:08 +0900 Subject: [PATCH 2/4] doc: remove platform update from plugin version management as update does not exist --- .../platform_plugin_versioning_ref/index.md | 38 +------------------ 1 file changed, 1 insertion(+), 37 deletions(-) diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md index bde90ef9e88..046a2e5f45e 100644 --- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md +++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md @@ -236,43 +236,7 @@ The `--nosave` flag could be appended to the command to prevent removal of speci _Note: If the plugin definition existed in `config.xml` from older version's of Cordova CLI, it will also be removed from `config.xml`._ -## Updating Platforms - -**Command Syntax:** - -```bash -cordova platform update [ ...] -``` - -You can update platforms using the command above. For details on valid `package-spec` formats, refer to the [Adding Platforms and Plugins](#Adding-Platforms-and-Plugins) section. - -_Note: The `update` command applies **only** to platforms._ - -### Various `update` Examples - -- **Cordova Resolved Name:** - - ```bash - cordova platform update android - ``` - - In addition to updating the `cordova-android` platform to the pinned version, it updates the `package.json` file. - - ```bash - cordova platform update android@13.0.0 - ``` - - This will update the platform to the targeted version. - -- **Local Directory Path:** - - ```bash - cordova platform update /path/to/android/platform - ``` - - In addition to updating the `cordova-android` platform to the local directory content, it will also update the `package.json` file pointing to the local directory path. - -### Important Notes on Platform Restoration +## Important Notes on Platform Restoration 1. What version is installed when using `cordova platform add android` and the platform is defined in `config.xml`? From dbbaefd6c85bec30318b7e46b856fa43930d004b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=82=A8=E3=83=AA=E3=82=B9?= Date: Wed, 12 Mar 2025 10:27:31 +0900 Subject: [PATCH 3/4] doc: Cordova resolved names requirement for platform removal applies only to Apache Cordova platforms --- www/docs/en/dev/platform_plugin_versioning_ref/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md index 046a2e5f45e..dccedbbd82e 100644 --- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md +++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md @@ -208,7 +208,7 @@ The `remove` command also has an alias of `rm`. The `package-name` argument must be the name of the platform or plugin you want to remove. -For platforms, you **MUST** use the [Cordova Resolved Names](#Cordova-Resolved-Names) when removing them. +For Apache Cordova's platforms, you **MUST** use the [Cordova Resolved Names](#Cordova-Resolved-Names) when removing them. The `--nosave` flag could be appended to the command to prevent removal of specified platform and plugins from the `package.json` file. From 6438f0f7b31f395653455fb1988d93c78288eba0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=82=A8=E3=83=AA=E3=82=B9?= Date: Wed, 12 Mar 2025 11:35:21 +0900 Subject: [PATCH 4/4] doc: improve Git URL formats description --- www/docs/en/dev/platform_plugin_versioning_ref/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md index dccedbbd82e..7bab969b73e 100644 --- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md +++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md @@ -158,9 +158,9 @@ When restoring a Cordova project, this metadata determines which platforms and p cordova platform add https://github.com/apache/cordova-android#rel/13.0.0 ``` - Various Git URL formats are supported for installing platforms and plugins. A branch name or tag can be specified by appending `#` to the URL. + Various Git URL formats are supported for installing platforms and plugins. Optionally, a treeish (branch name, tag, or commit ID) can be specified by appending `#` to the URL. - When targeting a branch or tag, ensure it is production-ready before using it in a production environment. This functionality is useful for reviewing pull requests, testing future releases, or submitting in release vote. + When targeting a treeish, ensure it is production-ready before using it in a production environment. This functionality is useful for testing and reviewing pull requests, future releases, or release votes. - **Git service short hand:**