testing.rst (7345B)
1 .. role:: bash(code) 2 :language: bash 3 4 .. role:: js(code) 5 :language: javascript 6 7 .. role:: python(code) 8 :language: python 9 10 ============================= 11 How to Test Migration Recipes 12 ============================= 13 14 To test migration recipes, use the following mach command: 15 16 .. code-block:: bash 17 18 ./mach fluent-migration-test python/l10n/fluent_migrations/bug_1485002_newtab.py 19 20 This will analyze your migration recipe to check that the :python:`migrate` 21 function exists, and interacts correctly with the migration context. Once that 22 passes, it clones :bash:`firefox-l10n-source` into :bash:`$OBJDIR/python/l10n`, creates a 23 reference localization by adding your local Fluent strings to the ones in 24 :bash:`firefox-l10n-source`. It then runs the migration recipe, both as dry run and 25 as actual migration. Finally it analyzes the commits, and checks if any 26 migrations were actually run and the bug number in the commit message matches 27 the migration name. 28 29 In most cases, a successful execution will only output the script execution: 30 31 .. code-block:: bash 32 33 Running migration fluent_migrations.bug_1994180_fix_manage_extensions_reference for en-US 34 Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl 35 Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 1 36 Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl 37 Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 2 38 39 In some instance, the output after execution will include a diff if there are 40 differences between the migrated files and the reference content (blank lines 41 are automatically ignored). There are cases where a diff is still expected, even 42 if the recipe is correct: 43 44 - If the patch includes new strings that are not being migrated, the diff 45 output will show these as removals. This occurs because the migration recipe 46 test contains the latest version of strings from :bash:`firefox-l10n-source` with 47 only migrations applied, while the reference file contains all string changes 48 being introduced by the patch. 49 - If there are pending changes to FTL files included in the recipe that landed 50 in the last few days, and haven't been pushed to :bash:`firefox-l10n-source` yet 51 (they're in the :bash:`update` branch of :bash:`firefox-l10n-source`), these will 52 show up as additions. 53 54 If a diff is displayed and the patch doesn't fall into the highlighted cases, 55 there may be an issue with the migration recipe. The example output below highlights 56 an instance where a migration failed to migrate a change to a string reference from 57 :bash:`{ unified-extensions-item-message-manage }` to 58 :bash:`{ unified-extensions-manage-extensions.label }`. 59 60 .. code-block:: bash 61 62 Running migration fluent_migrations.bug_1994180_fix_manage_extensions_reference for en-US 63 Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl 64 Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 1 65 Writing to /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl 66 Committing changeset: Bug 1994180 - Change unified-extensions-item-message-manage reference to unified-extensions-manage-extensions.label, part 2 67 --- /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/reference/browser/browser/unifiedExtensions.ftl 68 +++ /path/to/gecko/python/l10n/bug_1994180_fix_manage_extensions_reference/en-US/browser/browser/unifiedExtensions.ftl 69 @@ -17,8 +17,8 @@ 70 unified-extensions-empty-reason-extension-not-enabled = You have extensions installed, but not enabled 71 # In this headline, “Level up” means to enhance your browsing experience. 72 unified-extensions-empty-reason-zero-extensions-onboarding = Level up your browsing with extensions 73 -unified-extensions-empty-content-explain-enable2 = Select “{ unified-extensions-manage-extensions.label }” to enable them in settings. 74 -unified-extensions-empty-content-explain-manage2 = Select “{ unified-extensions-manage-extensions.label }” to manage them in settings. 75 +unified-extensions-empty-content-explain-enable2 = Select “{ unified-extensions-item-message-manage }” to enable them in settings. 76 +unified-extensions-empty-content-explain-manage2 = Select “{ unified-extensions-item-message-manage }” to manage them in settings. 77 unified-extensions-empty-content-explain-extensions-onboarding = Personalize { -brand-short-name } by changing how it looks and performs or boosting privacy and safety. 78 79 This diff output indicates that the string value being generated by the migration 80 (:bash:`Select “{ unified-extensions-item-message-manage }” to enable them in settings.`) 81 differs from the intended string value included in the Fluent file of the patch 82 (:bash: `{ unified-extensions-manage-extensions.label }`). 83 84 You can inspect the generated repository further by looking at 85 86 .. code-block:: bash 87 88 ls $OBJDIR/python/l10n/bug_1485002_newtab/en-US 89 90 Caveats 91 ------- 92 93 Be aware of hard-coded English context in migration. Consider for example: 94 95 96 .. code-block:: python 97 98 ctx.add_transforms( 99 "browser/browser/preferences/siteDataSettings.ftl", 100 "browser/browser/preferences/siteDataSettings.ftl", 101 transforms_from( 102 """ 103 site-usage-persistent = { site-usage-pattern } (Persistent) 104 """) 105 ) 106 107 108 This Transform will pass a manual comparison, since the two files are identical, 109 but will result in :js:`(Persistent)` being hard-coded in English for all 110 languages. 111 112 firefox-l10n-source repository 113 ------------------------------ 114 115 `firefox-l10n-source`_ is a unified repository including strings for all 116 shipping versions of Firefox, and is also used as a buffer before exposing strings 117 to localizers. There are typically two branches available, :bash:`main` and 118 :bash:`update`. The :bash:`main` branch acts as the source of truth for all 119 available strings exposed for localizaiton, while :bash:`update` acts as a 120 string quarantine. Migrations are run at the same time that strings are exposed 121 to localizers, that is when strings in :bash:`update` are merged into :bash:`main`. 122 123 When testing fluent recipes, the :bash:`fluent-migration-test` script relies on a 124 local clone of :bash:`firefox-l10n-source` located in :bash:`~/.mozbuild/l10n-source`. 125 When the mach command is run, the script either clones the remote repo if it doesn't 126 exist or pulls the latest changesets if :bash:`.git/l10n_pull_marker` is older than 127 2 days. Otherwise the current version is used. 128 129 Some advanced testing can be done by making changes in :bash:`~/.mozbuild/l10n-source` 130 such as checking out previous commits or adding strings manually. You can also force 131 sync to get the latest strings (if some have merged into :bash:`main` within the 132 2 day window) by manually pulling updates with git or by removing 133 :bash:`.git/l10n_pull_marker`. 134 135 .. _firefox-l10n-source: https://github.com/mozilla-l10n/firefox-l10n-source/