chore!: bump 9.0.0-dev and cordova-ios to 7.0.0

[GitToTheHub]

• cordova-ios 7 supports minimum iOS 11 which should be enough
• Removed wrong cordovaDependency for 5.0.4-dev. cordovaDependencies matches only against npm released versions.

Platforms affected

Motivation and Context

I wanted to fix the deprecation warnings for this plugin and noticed, that this plugin still supports iOS 8 because cordova-ios was set to 5.1.0. I set cordova-ios to 7.0.0, so the plugin minimum supports iOS 11 which will help to fix the deprecations.

Description

Testing

Checklist

• I've run the tests to see all new and existing tests pass
• I added automated test coverage as appropriate for this change
• Commit is prefixed with (platform) if this change only applies to one platform (e.g. (android))
• If this Pull Request resolves an issue, I linked to the issue in the text above (and used the correct keyword to close issues using keywords)
• I've updated the documentation if necessary

[dpogue]

You also need to update the engines listed in plugin.xml

[erisu]

This is my opinion, but I think this PR should be done a little differently.

Current PR Changes:

"8.0.0": {
    "cordova-android": ">=12.0.0",
    "cordova-ios": ">=5.1.0",
    "cordova": ">=9.0.0"
},
"8.0.1-dev": {
    "cordova-android": ">=12.0.0",
    "cordova-ios": ">=7.0.0",
    "cordova": ">=10.0.0"
},

Version 8.0.0 of the plugin already includes requirements and adding breaking changes should not be introduced in a patch or minor release.

We also never pinned -dev versions before here. I'm not fully sure how that behavior will play out.

I would recommend the following:

1. Update the PR title to something like: chore!: bump 9.0.0-dev
2. Update the package version in package.json, plugin.xml and any other necessary files to 9.0.0-dev.
3. Update the existing 9.0.0 version (which currently lists "cordova": ">100") to 10.0.0.
4. Replace the 8.0.1-dev entry, from this PR, with 9.0.0, without the -dev suffix.
5. Ensure that plugin.xml includes the same requirements.
6. Run npm install after making these changes so that package-lock.json is updated correctly.

IMO, I think we can use this PR to prepare for the 9.0.0 major development and future major release.

[GitToTheHub]

You also need to update the engines listed in plugin.xml

Regarding the plugin.xml documentation for the engines tag, it says:

NOTE: In Cordova 6.1.0+, the recommended place to specify platform, plugin, and CLI dependencies is in a plugin's package.json.

Since this plugin supports a Cordova version newer than 6.1.0, can I remove the engines configuration in plugin.xml?

[GitToTheHub]

@erisu I can do this with the 9.0.0-dev version.

Regarding point 4:

Replace the 8.0.1-dev entry, from this PR, with 9.0.0, without the -dev suffix. (in package.json)

When I set the version for this plugin in package.json to 9.0.0-dev but the version in for cordovaDependencies to 9.0.0, will the dependencies then apply to the dev version?

[erisu]

If I understand the plugin installation logic correctly, only the cordovaDependencies values from the latest published package are fetched and used. This means the versions we are defining here right now won't be available until the package is actually published. And since we never publish development packages—especially not under the latest tag—I don't see a reason to list any -dev versions. I believe it should only contain released versions. Since 9.0.0 will be a released version, it makes sense to include it, but even that won't take effect until it is published. I would also point out that the 5.0.4-dev entry is incorrect for the same reason.

At least, this is my understanding.

There might also be different behavior if searchpath values are provided or the noregistry flag is set but that is a workflow I never use, so I can't confirm how it behaves.

[GitToTheHub]

Understand, do you know why there is a special field cordovaDependencies? Could dependencies not used for it? Also I see, that the npm engines field is a little bit misused for it, cause it relates only the node or npm version to be used.

[dpogue]

The actual requirements that are enforced are as defined in the plugin.xml file engine elements.

The idea with the list of cordovaDependencies in package.json is that if you did cordova plugin add cordova-plugin-camera, the CLI tooling would look at the cordovaDependencies of the latest version of cordova-plugin-camera and check your local platform/tooling versions and then figure out which version of the plugin was actually compatible and install that one, rather than defaulting to the latest. I don't think that ever got fully implemented in the tooling through.

The platform versions should not be listed as dependencies because that would cause other platforms to potentially be downloaded when they aren't needed (i.e. an app that only targets Android could end up getting cordova-ios pulled in as an unnecessary dependency).

[GitToTheHub]

The actual requirements that are enforced are as defined in the plugin.xml file engine elements.

But do I understand wrong, that this can be replaced by cordovaDependencies in package.json? Why does the documentation say, that this is the replacement for the <engines> tag in plugin.xml? Is it wrong to remove the <engines> tag in plugin.xml, when cordovaDependencies is present in package.json? What do I miss here?

The idea with the list of cordovaDependencies in package.json is that if you did cordova plugin add cordova-plugin-camera, the CLI tooling would look at the cordovaDependencies of the latest version of cordova-plugin-camera and check your local platform/tooling versions and then figure out which version of the plugin was actually compatible and install that one, rather than defaulting to the latest. I don't think that ever got fully implemented in the tooling through.

I understand. If have for e.g. cordova-ios 7.0.0 installed, the cli looks in cordovaDependencies of a plugin which plugin version should be used for it. There would be no other good way, to determine the needed plugin version for cordova-ios 7.0.0.

The platform versions should not be listed as dependencies because that would cause other platforms to potentially be downloaded when they aren't needed (i.e. an app that only targets Android could end up getting cordova-ios pulled in as an unnecessary dependency).

I understand and makes sense. Maybe peerDependencies could be used for it along with peerDependenciesMeta. MaybepeerDependenciesMeta could be used to define which plugin version uses which Cordova related dependency. peerDependencies itself would than define Cordova dependencies for the latest plugin version.

[dpogue]

I recommend reading through https://github.com/apache/cordova-lib/blob/d2349bd6b4237ad512531e3b0ea2e6ab27cbf680/src/cordova/plugin/add.js#L311-L332 for background on the cordovaDependencies stuff. It's specifically not meant to be treated as dependencies of the plugin, but rather as requirements for the cordova tooling at plugin install time.

[GitToTheHub]

Thank you. I didn't see that the engines information of plugin.xml is used here, just package.json. Is this correct?

[dpogue]

engines is checked in a different spot in the plugin install process, once it has actually downloaded the files for a specific plugin version: https://github.com/apache/cordova-lib/blob/d2349bd6b4237ad512531e3b0ea2e6ab27cbf680/src/plugman/install.js#L100-L114

[erisu]

I think to summarize what @dpogue was explaining:

When a plugin is installed, the values defined in plugin.xml are the main deciding factor in whether the plugin is compatible with the project's current setup.

Following his example:

When the command cordova plugin add cordova-plugin-camera is executed, Cordova fetches the package's metadata from the npm registry and iterates through its cordovaDependencies to determine which version is actually compatible with the project. If the latest version is compatible, it will be used.

Once the version is decided and tries to run, it will run one more test against the values defined in plugin.xml.

The issue arises when cordovaDependencies includes a -dev version. If that version was identified as the "compatible" one and attempted to be fetched, it will fail because dev versions are never published to npm.

In the case of installing from a local directory or repo, I think it skips this process.

Using npm's properties—dependencies, devDependencies, optionalDependencies, and peerDependencies—wouldn't serve the same purpose as cordovaDependencies. At best, peerDependencies might be able to replace the engines tags in plugin.xml, as long as it doesn't automatically install or block anything. However, it may warn users that they need to install certain platforms or the CLI in their project, even if they don't actually support that platform or that they prefer using a global install of CLI.

[GitToTheHub]

Thank you @erisu, for explaining everything. So the documentation is wrong about the <engines> tag is deprecated in plugin.xml? Because currently the documentation encourages plugin developers to just use cordovaDependencies and not additionally the <engines> in plugin.xml. Should this changed in the documentation or make it more clear?

[dpogue]

I think this looks good now

[GitToTheHub]

@erisu I did everything like you mentioned in #939 (review). Also I removed the wrong dependency entry for 5.0.4-dev. I let the cordova version untouched to 9.0.0, so it's currently only focussed on bumping the plugin version and cordova-ios version.

[GitToTheHub]

I think this looks good now

I'm glad 😃

[erisu]

Thank you @erisu, for explaining everything. So the documentation is wrong about the <engines> tag is deprecated in plugin.xml? Because currently the documentation encourages plugin developers to just use cordovaDependencies and not additionally the <engines> in plugin.xml. Should this changed in the documentation or make it more clear?

I do not see any statements indicating that the <engines> tag is deprecated, but I do see this:

NOTE: In Cordova 6.1.0+, the recommended place to specify platform, plugin, and CLI dependencies is in a plugin's package.json. See Specifying Cordova Dependencies for more information.

If anything, I would suggest updating it to:

NOTE: Starting in Cordova 6.1.0, it is recommended to include the platform and CLI engine requirements in the plugin's package.json, in addition to the <engines> declaration in plugin.xml. See Specifying Cordova Dependencies for more information.

This wording uses phrases like "include" and "in addition to the <engines>" to make it clear that the <engines> tag is not deprecated, and it would be helpful if authors also included cordovaDependencies.

---

Also, in the Specifying Cordova Dependencies documentation, there is this statement:

This feature is intended to eventually replace the engines element in plugin.xml.

I would not change this. It says "intended to" which does not imply deprecation. It simply describes the long-term goal, which has not yet been completed.

---

This suggestion is just my opinion...

[GitToTheHub]

I wonder if a plugin will work, if cordovaDependencies is not specified in package.json. Could I ommit it in the recent cordova-cli version? I'm asking, because the documentation talks currently more like it is optional.