doc: update 12.x 2025.01 snapshot

[erisu]

Motivation and Context

Sync current changes into 12.x 2025.01 snapshot

Description

Updated current docs 12.x 2025.01

Documentation appears to include

• Contains various refactoring of existing content
• Added AndroidShowDeprecations and CrashRecoveryBehavior
• Added of Android 14
• Improved how to use Cordova Android in native app
• Includes Cordova iOS 8.x release
• Removal of more deprecated platform content from plugins.

Note

Cordova-Android was released in March, not January, as this snapshot suggests. Additionally, the snapshot refers to Cordova-CLI, not the platforms.

Keep in mind that platforms are not tied to specific CLI versions.

This PR may also contain content from the Cordova-iOS 8 official release, not just the beta release.

Testing

n/a

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

[GitToTheHub]

Nice, I was not aware than in fact all changes in dev could be synced to 12.x as long as they don't depend on 13.x. Good thing, that you started the email discussion about the documentations.

[GitToTheHub]

Can this be also synchronized to 12.x?

[erisu]

I'm not sure I would recommend synchronizing with 12.x.
Cordova-CLI 12.x is more than three years old, and there have been many
platform releases since then. Also 12.x-2025.1 is current docs, not 12.x.

Platform pinning was also removed in 12.x. Given that pinning is no longer
used, perhaps 12.x could simply be identical to 12.x-2025.1.

Maybe we should revert the snapshot logic to remove the -{YEAR}.{MONTH}
suffix?

I'm hoping we can reach a decision through the mailing list thread.

[GitToTheHub]

If find a doc tag like 12.x-2025.1. confusing. Because the doc version currently relates to a cordova-cli version and there does not exists a version like 12.x-2025.1.. So I would be for removing the snapshot suffix.

[erisu]

One use case to keep in mind:

Cordova-CLI does not usually receive frequent updates because of how stable it is.

For example, the gap between Cordova-CLI 12.x and 13.x was about three years. During that time, Cordova-Android may have had three major releases. Across those majors, something could have been deprecated and removed.
If we delete items from the docs, then the 12.x documentation from three years ago, which show something as supported is now missing that information all of a sudden.

That is the potential issue, and that is why started to date the snapshots so that we could introduce such changes.

This is why I created the discussion thread on the mailing list to try and come up with some solution to solve various doc problems, versioning being one of them.

[GitToTheHub]

Maybe we could snapshot the documentations for the platform versions? This would be more logical.

[breautek]

Maybe we could snapshot the documentations for the platform versions? This would be more logical.

Wouldn't make much sense in practice with how the docs are built where it includes all the platforms, so a particular build isn't behind a particular platform.

Currently the docs is "tied" to the CLI version because once upon a time, platforms was tied to a particular CLI version, there was a coupled dependency. But as the CLI matured, we found that we could go many platform releases without releasing a CLI version. So we started allowing wider range of CLI versions to be used across different platform versions.

Today the CLI is completely decoupled from the platforms, and we just always assume that if you install a platform you want the latest version unless if there is a hint in the project somewhere that suggest otherwise. That's kind of the history of how we got where we are today with the docs.

The discussion over here I think suggests some really good paths including removing the snapshot logic altogether. The docs becomes more of a live document that just simply gets updated rather than having versions. Documented features will simply be annotated for platform support.

I think we will still have archives, which is effectively a snapshot in a particular moment of time, which we will likely use before we do any kind of documentation cleanup (such as deleting information for old deprecated APIs that has been removed from the framework for some time). But these archives will not be something of focus, it will probably be a link to an archive index perhaps in the footer. All of this is not set in stone, just kind of brainstorming.