feat(developer): introduce WelcomeFile property to packages 🎺

[mcdurdin]

Fixes #9478.

This adds a property WelcomeFile to .kps and kmp.json, which allows us to move away from the hardcoded welcome.htm filename in the future, and makes transform from Markdown (#9477) a simpler operation, and just generally starts the cleanup of the messiness of hard-coded filenames.

The package compiler will fallback to injecting welcome.htm into this property if (a) welcome.htm is present, and (b) the property does not already have a value. This doesn't buy us much because we still need to support welcome.htm for existing legacy packages, but does mean that our .kmp package metadata will be more consistent for packages compiled with 17.0+ compilers.

User Testing

Note: Keyman itself on all platforms still only supports the welcome.htm filename at this time, so do not expect documentation with arbitrary filenames to be visible in the client apps.

TEST_WELCOME_FILE: In the package editor in Keyman Developer, select a welcome.htm file in the new Documentation file field. Compile the package and verify that there are no errors. Add and remove the reference to the documentation file and verify that the field behaves as you would expect.

[keymanapp-test-bot]

User Test Results

Test specification and instructions

• ✅ TEST_WELCOME_FILE (PASSED): Retested as per Marc's suggestion and here is my observation: 1. Opened Khmer_Angkor keyboard project. 2. Opened the Package Editor. Run compile keyboard. Verified that there were no errors in the console window. 3. Added Welcome.htm file in the 'Welcome file' documentation field. Run compile keyboard. Did not find any error message. 4. Removed the Welcome.htm file from the documentation field. Run compile keyboard. Did not see any error message. Seems to be working as expected. (notes)

Test Artifacts

• Android
  • Keyman for Android apk
  • FirstVoices for Android 16.0 apk
  • FirstVoices Keyboards for Android apk
  • KeyboardHarness apk
  • Keyman for Android 16.0 apk
  • KMSample1 apk
  • KMSample2 apk
• Developer
  • Keyman Developer
  • Compiler Regression Tests
  • kmcomp.zip
• iOS
  • Keyman for iOS (simulator image)
  • FirstVoices Keyboards for iOS (simulator image)
  • TestFlight internal PR build version - 17.0.187 (0.9709.9372)
• Keyboards
  • Test Keyboards
• Web
  • KeymanWeb Test Home
• Windows
  • Keyman for Windows
  • FirstVoices Keyboards for Windows
  • Text Editor (32 bit)
  • Text Editor (64 bit)

[rc-swag]

How doe the FAllow boolean fit in with these procedures?

[mcdurdin]

The FAllow var parameter is an output parameter, allowing the function to prevent the removal of the item, which we never need to do, so it's safely ignored.

[bharanidharanj]

Test Results

• TEST_WELCOME_FILE (PASSED): Tested with the attached Keyman Developer 17.0.187-alpha-test-9709 in Windows 10 OS and here is my observation: 1. Opened khmer_angkor keyboard project. 2. Opened the welcome.htm file in the documentation file field. In the package editor, compiled the package and verified that there were no errors. 3. Removed the reference to the documentation file and verified that there were no errors after the compilation. Seems to be working as expected.

..with reference file in welcome.htm after compiling the package

..without reference file in welcome.htm after compiling the package

[mcdurdin]

@bharanidharanj I think perhaps my test steps were not very clear, sorry!

There is a new field in the Package Editor, called "Documentation File", in the Details tab, which we need to test. I don't have an image handy sorry as my machine is on a different branch, but it should be at the top of the "Optional Information" section of the tab, above the "Readme file" entry.

Would you mind re-testing? Thanks so much!

@keymanapp-test-bot retest

[bharanidharanj]

@bharanidharanj I think perhaps my test steps were not very clear, sorry!

There is a new field in the Package Editor, called "Documentation File", in the Details tab, which we need to test. I don't have an image handy sorry as my machine is on a different branch, but it should be at the top of the "Optional Information" section of the tab, above the "Readme file" entry.

Would you mind re-testing? Thanks so much!

@keymanapp-test-bot retest

@mcdurdin Thank you so much for your clarification! I will retest and add my post my results.

[bharanidharanj]

Test Results

• TEST_WELCOME_FILE (PASSED): Retested as per Marc's suggestion and here is my observation: 1. Opened Khmer_Angkor keyboard project. 2. Opened the Package Editor. Run compile keyboard. Verified that there were no errors in the console window. 3. Added Welcome.htm file in the 'Welcome file' documentation field. Run compile keyboard. Did not find any error message. 4. Removed the Welcome.htm file from the documentation field. Run compile keyboard. Did not see any error message. Seems to be working as expected.

..Added welcome.htm file in the 'Welcome file' documentation field

..Removed welcome.htm file in the 'Welcome file' documentation field

[rc-swag]

lgtm