Skip to content

Keyman 13.0 to 14.0 Migration

Jump to bottom
Darcy Wong edited this page May 1, 2020 · 37 revisions

How to use this document

This document is a work-in-progress capturing changes between 13.0 and 14.0 of Keyman. It will be transferred to help.keyman.com on the release of version 14.0.

Don't worry too much about getting the wording totally consistent. The aim here is to capture the knowledge of changes while they are fresh. We will review and tidy up the document before release.

If a change may introduce issues for other developers, mark it with BREAKING.

This does not necessarily need to correspond to pull request IDs as in many cases there may be many PRs for one issue. If you can do this, then good, but don't stress over it.

You can make good use of HISTORY.md for populating this initially.

Versioning

Keyman 14.0 moves to a synchronized build number across all platforms. This means that for some critical fixes there may be a release that impacts only one platform, but all platforms will have a version bump. We considered the advantages of having consistent versioning outweighed this one situation. The plan going forward is that we will bundle sets of bug fixes across multiple platforms for stable releases, to avoid this situation.

We anticipate renaming the Keyman Desktop and Keyman Developer installers to exclude the final .0, e.g. keymandesktop-14.0.99.exe instead of keymandesktop-14.0.99.0.exe.

Significant and Breaking Changes for Developers

Anything that other developers should be aware of should be documented here. This set of people includes:

  • Keyboard developers
  • Developers of websites that use KeymanWeb
  • Developers of apps that embed or interface with Keyman Engine (KAB, FieldWorks, etc)
  • Tool developers, e.g. .kmn language changes may impact other tools

Include major new functionality that they may need to cater to, and anything that changes the way someone may use Keyman from a development perspective. Changes to functionality that impact end users may be documented here, but that is not the core purpose of this document.

All Platforms

  • We have moved to using Sentry for bug reporting.

Windows

  • Keyman Desktop now uses Chromium to host all web-based UI (e.g. Keyman Configuration).

    • Help, Hint dialogs were moved from keyman.exe to kmshell.exe to facilitate this. This means a small change in keyman.exe's shutdown sequence.
    • Hint banners in the On Screen Keyboard were removed. This is a minor loss in functionality.
    • IE-specific weirdisms in the UI .xsl files may need to be resolved for Keyman Engine users.
    • BREAKING: Keyman Engine no longer supports the keyboard usage page (usage.htm). This was a security and architectural decision which we were forced to take when we integrated with Chromium -- keyman.exe necessarily operates in a higher security level (uiAccess=true in the manifest) in order to interop with other process keyboard input. This means that hosting arbitrary web pages (usage.htm) is dangerous and Chromium does not run in this context without modification. However, only one keyboard published in the repository included a usage.htm: sil_euro_latin 'European Latin' (and its variants). This is a loss in functionality for which we are considering ways to address in the future, but it is currently unlikely that we can reintroduce web-based functionality like this.
    • On a more positive note, Keyman Engine now has no dependencies on Chromium or IE. All web-based UI interactions are in kmshell.exe.

  • User interface localization is now managed through Crowdin and updates and new translations are bundled with Keyman Desktop. The old tavultesoft.com-based online localization tool has been retired. Manual editing of the localization files may lead to inconsistencies with the Crowdin sources.

macOS

iOS

Android

  • BREAKING: Moved from API 19 to minimum API level 21 (Lollipop / Android 5.0) with corresponding Chromium minimum release M37.
  • BREAKING: Replaced Fabric/Crashlytics with Sentry for crash reporting
    • build.gradle changes: 
      android {
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

dependencies {
  implementation 'io.sentry:sentry-android:2.0.1'
}
  • BREAKING: KMManager API (deprecating use of cloud keyboard catalog info and using embedded browser for keyboard search)
  • KMManager API ("Custom" property for keyboards/lexical models no longer tracked)
    • Deprecated KMManager.KMKey_CustomKeyboard and KMManager.KMKey_CustomModel properties
  • Use keyboard / lexical model packages instead of standalone .js files
    • Keyboards now strictly installed from .kmp keyboard packages. 3rd party apps should include their "default" keyboard and lexical model packages at the project's assets/ level. KMManager will extract them into assets/packages/ and assets/models/ respectively. (No longer append version string to .js keyboard file and manually copy to assets/cloud/ folder)

Linux

Web

  • BREAKING: Ceased support for Internet Explorer altogether.
  • BREAKING: No longer testing against legacy Edge.

Developer

  • Added ISO9995 key ids (e.g. + [SHIFT E01] > 'ooh'). These compile down to their US VKeys so there is no change in compiled keyboards, but parsers of .kmn files may need to be aware of this.

Known Issues

Windows

  • The delineation between Keyman Engine and Keyman Desktop is currently blurry and needs further work. It is likely that embedders of Keyman Engine will need kmshell.exe for some operations but this has not yet been assessed.
Clone this wiki locally