Sync knowledge articles with review agent instructions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

microsoft/knowledge/upgrade/assess-existing-data-before-key-or-type-changes.md

@@ -0,0 +1,22 @@
+---
+bc-version: [all]
+domain: upgrade
+keywords: [primary-key, field-type, existing-data, schema, breaking-change]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Assess existing data before primary-key or field-type changes
+
+## Description
+
+Primary-key and field-type changes are upgrade concerns because existing rows may no longer map safely to the new schema. The risk depends on whether the table already has tenant data and whether the old values can be converted without loss. New feature tables with no production rows do not have the same migration burden as ledger, document, or base application tables.
+
+## Best Practice
+
+For existing tables with data, require a concrete migration or compatibility assessment before changing keys or field types. For new tables, new feature tables, or Integer-to-BigInteger changes with evidence that existing values fit, avoid flagging a breaking-change finding without data-impact evidence.
+
+## Anti Pattern
+
+Treating every primary-key edit in a new feature table as a blocker while missing a key or type change on an established ledger-like table. Reviewers need to tie the finding to existing tenant data, not just to the syntactic shape of the schema edit.

microsoft/knowledge/upgrade/do-not-make-external-calls-in-upgrade-codeunits.md

@@ -15,7 +15,7 @@ The upgrade scope has to complete for the tenant to reach the new version. Any c
 
 ## Best Practice
 
-Defer external calls to runtime code that executes after the upgrade — install-triggered tasks, background job queue entries scheduled by the upgrade, or lazy initialization on first use. The upgrade step should compute a local result or mark work to be done, not perform the remote call itself.
+Defer external calls to runtime code that executes after the upgrade — install-triggered tasks, background job queue entries scheduled by the upgrade, or lazy initialization on first use. The upgrade step should compute a local result or mark work to be done, not perform the remote call itself. Do not apply this rule to ordinary runtime codeunits, pages, tables, install procedures, or background jobs unless they are directly invoked from an upgrade trigger.
 
 ## Anti Pattern
 

microsoft/knowledge/upgrade/exclude-hybrid-migration-codeunits-from-standard-upgrade-rules.md

@@ -0,0 +1,22 @@
+---
+bc-version: [all]
+domain: upgrade
+keywords: [hybrid, migration, upgrade-tag, false-positive, datamigration]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Exclude Hybrid migration codeunits from standard upgrade rules
+
+## Description
+
+Hybrid migration codeunits such as `HybridBC14`, `HybridSL`, `HybridGP`, and `HybridBaseDeployment` are one-time migration paths with established migration-specific patterns. They are not ordinary `Subtype = Upgrade` steps, and forcing standard upgrade-tag, trigger-shape, or missing-upgrade-code rules onto them creates false positives.
+
+## Best Practice
+
+When a change is clearly in a Hybrid migration codeunit or migration namespace, review it against migration-specific data handling and destination classification rules. Do not flag it merely because it lacks ordinary upgrade tags or because its control flow differs from standard upgrade codeunits.
+
+## Anti Pattern
+
+Reporting "missing upgrade tag" or "missing standard upgrade code" on a `HybridSL`, `HybridGP`, `HybridBC`, or `HybridBaseDeployment` codeunit solely because it does not look like a normal upgrade step. The name and migration context are the signal that different rules apply.

microsoft/knowledge/upgrade/guard-performance-impacting-upgrade-triggers.bad.al

@@ -0,0 +1,13 @@
+codeunit 50831 "Upgrade Sample Trigger Bad"
+{
+    Subtype = Upgrade;
+
+    trigger OnValidateUpgradePerCompany()
+    begin
+        ValidateAllCustomers();
+    end;
+
+    local procedure ValidateAllCustomers()
+    begin
+    end;
+}

microsoft/knowledge/upgrade/guard-performance-impacting-upgrade-triggers.good.al

@@ -0,0 +1,25 @@
+codeunit 50830 "Upgrade Sample Trigger Good"
+{
+    Subtype = Upgrade;
+
+    trigger OnValidateUpgradePerCompany()
+    var
+        UpgradeTag: Codeunit "Upgrade Tag";
+    begin
+        // Required for regulatory data validation before this release can run.
+        if UpgradeTag.HasUpgradeTag(ValidationTag()) then
+            exit;
+
+        ValidateAllCustomers();
+        UpgradeTag.SetUpgradeTag(ValidationTag());
+    end;
+
+    local procedure ValidateAllCustomers()
+    begin
+    end;
+
+    local procedure ValidationTag(): Code[250]
+    begin
+        exit('MS-000010-ValidateCustomers-20260501');
+    end;
+}

microsoft/knowledge/upgrade/guard-performance-impacting-upgrade-triggers.md

@@ -0,0 +1,26 @@
+---
+bc-version: [all]
+domain: upgrade
+keywords: [onvalidateupgrade, trigger, upgrade-tag, performance, justification]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Guard performance-impacting upgrade triggers
+
+## Description
+
+Upgrade validation triggers such as `OnValidateUpgradePerCompany` can run during upgrade for every tenant and company. Expensive validation, full-table scans, or repair logic in those triggers becomes part of the upgrade's critical path. The trigger is acceptable only when the work is necessary and when re-execution is prevented.
+
+## Best Practice
+
+Add written justification for the trigger's work and guard it with an upgrade tag just like a data-migration step. Check `HasUpgradeTag` before the expensive work and call `SetUpgradeTag` only after the work succeeds, so retries do not re-run completed validation.
+
+See sample: `guard-performance-impacting-upgrade-triggers.good.al`.
+
+## Anti Pattern
+
+Putting `ValidateAllCustomers()`, table scans, or external-style setup validation directly in `OnValidateUpgradePerCompany` without a skip tag. The work runs on every upgrade attempt, including retries after unrelated failures.
+
+See sample: `guard-performance-impacting-upgrade-triggers.bad.al`.

microsoft/knowledge/upgrade/initvalue-does-not-populate-existing-records.md

@@ -15,7 +15,7 @@ The `InitValue` property sets a field's default for rows created after the field
 
 ## Best Practice
 
-When adding a field to an existing table with a meaningful default, write an upgrade step that populates existing rows with the same value, guarded by its own upgrade tag. Use `DataTransfer` with `AddConstantValue` for set-based initialization (see `use-datatransfer-for-large-dataset-initialization`). Exceptions: brand-new tables, new Boolean fields where `false` is the correct value for existing rows, and informational fields where empty is an acceptable state.
+When adding a field to an existing table with a meaningful default, write an upgrade step that populates existing rows with the same value, guarded by its own upgrade tag. Use `DataTransfer` with `AddConstantValue` for set-based initialization (see `use-datatransfer-for-large-dataset-initialization`). Exceptions: brand-new tables; new Boolean fields without InitValue where `false` is the intended existing-row value; new extensions, new feature tables, or setup tables with no meaningful existing data to migrate; and informational fields where empty is an acceptable state.
 
 See sample: `initvalue-does-not-populate-existing-records.good.al`.
 

microsoft/knowledge/upgrade/register-upgrade-tags-with-subscribers.md

@@ -15,12 +15,12 @@ An upgrade tag set via `UpgradeTag.SetUpgradeTag` only participates in the platf
 
 ## Best Practice
 
-For every upgrade-tag constant referenced in `HasUpgradeTag`/`SetUpgradeTag`, register it in the subscriber that matches its trigger scope: tags used from `OnUpgradePerCompany` go in `OnGetPerCompanyUpgradeTags`; tags used from `OnUpgradePerDatabase` go in `OnGetPerDatabaseUpgradeTags`. Keep the tag string in a single source (Label or function) and reference it at the guard, the setter, and the registration.
+For every upgrade-tag constant referenced in `HasUpgradeTag`/`SetUpgradeTag`, register it in the subscriber that matches its trigger scope: tags used from `OnUpgradePerCompany` go in `OnGetPerCompanyUpgradeTags`; tags used from `OnUpgradePerDatabase` go in `OnGetPerDatabaseUpgradeTags`. Treat this mapping as a review point, not just a naming convention. Keep the tag string in a single source (Label or function) and reference it at the guard, the setter, and the registration.
 
 See sample: `register-upgrade-tags-with-subscribers.good.al`.
 
 ## Anti Pattern
 
-Adding a new `UpgradeTag.SetUpgradeTag(MyTag())` without the matching `PerCompanyUpgradeTags.Add(MyTag())` in the registration subscriber. The code compiles and the step completes, but the tag is unregistered and the infrastructure is partially disabled.
+Adding a new `UpgradeTag.SetUpgradeTag(MyTag())` without the matching `PerCompanyUpgradeTags.Add(MyTag())` in the registration subscriber, or registering a tag used from `OnUpgradePerCompany` in `OnGetPerDatabaseUpgradeTags`. The code compiles and the step completes, but the tag is invisible or registered at the wrong scope.
 
 See sample: `register-upgrade-tags-with-subscribers.bad.al`.

microsoft/knowledge/upgrade/use-datatransfer-for-large-dataset-initialization.md

@@ -11,13 +11,13 @@ application-area: [all]
 
 ## Description
 
-An upgrade that populates a new field on millions of existing rows with a FindSet+Modify loop pays a round-trip and a per-row trigger invocation for every row — turning a multi-hour upgrade into a multi-day one on ledger-entry-scale tables. `DataTransfer` pushes the update to SQL as a single set-based operation using source filters and constant values, which is the supported platform mechanism for this scenario. The tradeoff: DataTransfer bypasses validation triggers and event subscribers — if the step depends on trigger logic, that has to be reconstructed explicitly.
+An upgrade that populates a new field on existing rows with a FindSet+Modify loop pays a round-trip and a per-row trigger invocation for every row — turning a multi-hour upgrade into a multi-day one on ledger-entry-scale tables. `DataTransfer` pushes the update to SQL as a single set-based operation using source filters and constant values, which is the supported platform mechanism for this scenario. The tradeoff: DataTransfer bypasses validation triggers and event subscribers — if the step depends on trigger logic, that has to be reconstructed explicitly.
 
 ## Best Practice
 
-Use DataTransfer when initializing a new field on an existing table that **can contain more than 300,000 records**, or whenever a new field is added to an existing table and the initialization must run across all existing rows. Tables in the ledger-entry and document-line category reliably exceed this threshold; treat them as requiring DataTransfer by default.
+Use DataTransfer when a new field added to an existing table needs initialization across existing rows, and for any table that can contain more than 300,000 records. Tables in the ledger-entry and document-line category reliably exceed this threshold; treat them as requiring DataTransfer by default.
 
-Set tables, add source filters, add constant values, call CopyFields, clear, and repeat for additional slices. When trigger or subscriber behaviour is required, do that work separately against a filtered result set so the bulk update remains set-based.
+Set tables, add source filters, add constant values, call CopyFields, clear, and repeat for additional slices. Use the pattern for new fields and tables added in the same change. If no new field or table is involved, document why validation triggers and event subscribers are safe to bypass, or keep the explicit loop that invokes the business logic.
 
 See sample: `use-datatransfer-for-large-dataset-initialization.good.al`.
 

microsoft/knowledge/upgrade/use-upgrade-tags-not-version-checks.md

@@ -15,12 +15,12 @@ application-area: [all]
 
 ## Best Practice
 
-Guard each step with `if UpgradeTag.HasUpgradeTag(MyTag()) then exit;` at the top of the procedure. After the step completes, call `UpgradeTag.SetUpgradeTag(MyTag())`. Define the tag string in a `Tok`-suffixed Label or returning function so the same constant is referenced at both the guard and the registration (see `register-upgrade-tags-with-getpercompany-getperdatabase-subscribers`).
+Guard each standard upgrade step with `if UpgradeTag.HasUpgradeTag(MyTag()) then exit;` at the top of the procedure. After the step completes, call `UpgradeTag.SetUpgradeTag(MyTag())`. Define the tag string in a `Tok`-suffixed Label or returning function so the same constant is referenced at both the guard and the registration (see `register-upgrade-tags-with-getpercompany-getperdatabase-subscribers`). The supported DataVersion exception is first-install detection in `OnInstallAppPerCompany` with the `0.0.0.0` sentinel; one-time Hybrid migration codeunits follow separate migration patterns and should not be forced into ordinary upgrade-tag structure.
 
 See sample: `use-upgrade-tags-not-version-checks.good.al`.
 
 ## Anti Pattern
 
-`if MyApp.DataVersion().Major < 18 then UpgradeFeatureA();` — the step runs on every upgrade from a pre-18 version, may fail on partial data, and the next retry re-runs work that already succeeded. Nesting version-check branches (`< 14` → step A, `< 17` → step B) compounds the fragility.
+`if MyApp.DataVersion().Major < 18 then UpgradeFeatureA();` inside a standard upgrade step — the step runs on every upgrade from a pre-18 version, may fail on partial data, and the next retry re-runs work that already succeeded. Nesting version-check branches (`< 14` → step A, `< 17` → step B) compounds the fragility.
 
 See sample: `use-upgrade-tags-not-version-checks.bad.al`.