Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-08-06 17:36:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/upgrade/enum-changes-must-be-additive-at-the-end.md
Jesper Schulz-Wedde dc14e7bb2a Update 6 knowledge articles to align with revised instructions 
- performance/use-setloadfields-for-partial-records: Clarify that
  filter-only fields (SetRange/SetFilter) do not need to be listed in
  SetLoadFields — the DB resolves them via the index without hydrating
  the value into AL memory.

- performance/avoid-calcfields-in-loops: Add explicit exception for
  OnAfterGetRecord and OnValidate triggers, which are platform-managed
  and not developer-authored loops.

- performance/split-read-only-and-write-paths-to-avoid-locktable: Add
  ReadIsolation as the primary recommendation for read-only paths;
  LockTable reserved for confirmed write paths only.

- performance/prefer-direct-record-over-recordref: Scope the finding to
  hot unbounded loops (10k+ rows) over ledger-entry-scale tables;
  RecordRef in bounded/admin/setup contexts is not a concern.

- upgrade/enum-changes-must-be-additive-at-the-end: Replace direct
  ObsoleteState = Removed guidance with the two-stage workflow (Pending
  first, Removed later); reference use-obsolete-pending-before-removed.

- upgrade/use-datatransfer-for-large-dataset-initialization: Add the
  >300,000 records threshold as the concrete trigger for requiring
  DataTransfer.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-24 10:36:08 +02:00

1.8 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
upgrade
enum
ordinal
obsolete
backward-compatibility
breaking-change
al
w1
all

Enum changes must be additive at the end; never insert or remove values

Description

AL enums store their ordinal on disk. Inserting a new value in the middle of an existing enum shifts every following ordinal by one: every row whose field holds the old ordinal N now resolves to the value that used to be N+1. Removing a value without obsoletion has the same effect. Both changes are data corruption disguised as a code edit and are effectively irreversible once a tenant has upgraded. Adding values at the end is safe — existing ordinals keep their meaning.

Best Practice

Append new enum values at the end, taking the next free ordinal. Renaming the caption on an existing ordinal is fine.

When a value must be retired, follow the two-stage obsoletion workflow:

  1. First release: Mark the value with ObsoleteState = Pending, ObsoleteReason, and ObsoleteTag. This gives callers at least one release cycle to migrate.
  2. Later release: Advance to ObsoleteState = Removed once all callers have been updated.

Never skip straight to ObsoleteState = Removed without first going through Pending — doing so removes the warning cycle that callers depend on. Do not reclaim the ordinal in either stage. See also: use-obsolete-pending-before-removed.md.

See sample: enum-changes-must-be-additive-at-the-end.good.al.

Anti Pattern

Inserting value(1; "NewMiddleValue") between existing value(0; "First") and the original value(1; "Second"). Every row that stored ordinal 1 before the change now reads as NewMiddleValue. The same applies to removing a value outright without obsoletion.

See sample: enum-changes-must-be-additive-at-the-end.bad.al.