mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 17:36:53 +01:00
dc14e7bb2a
- 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>
33 lines
1.8 KiB
Markdown
33 lines
1.8 KiB
Markdown
---
|
|
bc-version: [all]
|
|
domain: upgrade
|
|
keywords: [enum, ordinal, obsolete, backward-compatibility, breaking-change]
|
|
technologies: [al]
|
|
countries: [w1]
|
|
application-area: [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`.
|