Fix lifecycle compatibility guidance (#93)

* Fix lifecycle compatibility guidance

Correct high-confidence Business Central guidance and samples for upgrade tags, collectible errors, trigger semantics, obsoletion, events, interfaces, API contracts, and test transactions.

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

Copilot-Session: e05a43e7-6448-4d67-9c73-798523f5d945

* Address guidance review findings

Gate SecretText guidance to BC23 and clarify that the collectible-error sample intentionally emits a message-only blocking aggregate.

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

Copilot-Session: e05a43e7-6448-4d67-9c73-798523f5d945

---------

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>

microsoft/knowledge/breaking-changes/deprecate-public-members-with-the-obsolete-lifecycle.good.al

@@ -1,7 +1,7 @@
 codeunit 50305 "Net Amount Api Good"
 {
-    // Old name kept and marked obsolete: callers still compile but get a warning
-    // pointing at the replacement, with a tag recording the removal target version.
+    // Old name kept during the warning window. The tag records when obsoletion
+    // began; a later release deletes the method after consumers have migrated.
     [Obsolete('Use CalculateNetAmount instead.', '25.0')]
     procedure CalcNet(GrossAmount: Decimal; TaxRate: Decimal): Decimal
     begin

microsoft/knowledge/breaking-changes/deprecate-public-members-with-the-obsolete-lifecycle.md

@@ -11,16 +11,16 @@ application-area: [all]
 
 ## Description
 
-Deleting or renaming a published procedure (or object) in a single release is a hard break: dependent extensions that reference it stop compiling the moment they pick up the new version, with no warning window to migrate. AL provides a staged deprecation lifecycle precisely so consumers get advance notice. For a procedure, apply the `[Obsolete('reason', 'tag')]` attribute: the member keeps working but every caller gets a compiler warning naming the replacement and the target version. The member stays through a deprecation window — at least one major release — before it is finally removed. Object- and field-level members use the matching `ObsoleteState = Pending` → `Removed` property progression. LLMs trained to "clean up" code often delete or rename the old member immediately, skipping the window entirely.
+Deleting or renaming a published procedure (or object) in a single release is a hard break: dependent extensions that reference it stop compiling the moment they pick up the new version, with no warning window to migrate. AL provides staged deprecation so consumers get advance notice. A procedure uses `[Obsolete('reason', 'tag')]`: it remains callable but callers receive a compiler warning naming the replacement and the version in which obsoletion began. Methods do not have `ObsoleteState`; after the deprecation window, the method is deleted, commonly through versioned preprocessor cleanup. Objects and fields instead use the `ObsoleteState = Pending` to `Removed` property progression.
 
 ## Best Practice
 
-When a published procedure is superseded, keep it in place and mark it `[Obsolete('Use CalculateNetAmount instead.', '25.0')]`, where the message names the replacement and the tag records the target version for removal. Have the obsolete member forward to the new one so behavior is preserved during the window. Only after the deprecation window has elapsed — a later release — change its state to removed. This gives every dependent app a compile-time signal and time to migrate before anything actually disappears.
+When a published procedure is superseded, keep it in place and mark it `[Obsolete('Use CalculateNetAmount instead.', '25.0')]`, where the message names the replacement and the tag records when the method became obsolete. Have the obsolete member forward to the new one so behavior is preserved during the window. Only after the deprecation window has elapsed should a later release delete the method. For an object or field, use `Pending` during the warning window and `Removed` afterward.
 
 See sample: `deprecate-public-members-with-the-obsolete-lifecycle.good.al`.
 
 ## Anti Pattern
 
-Renaming or deleting the published `CalcNet` procedure in place — replacing it with `CalculateNetAmount` and nothing else — so consumers calling `CalcNet` break immediately with no deprecation notice. Detection: a previously shipped non-`local` procedure that vanished or was renamed between versions with no `[Obsolete]` marker left behind on a kept member. Mark it obsolete and keep it for a window instead.
+Renaming or deleting the published `CalcNet` procedure in place — replacing it with `CalculateNetAmount` and nothing else — so consumers calling `CalcNet` break immediately with no deprecation notice. Detection: a previously shipped non-`local` procedure that vanished or was renamed between versions with no `[Obsolete]` marker left behind during a prior warning window. Do not suggest `ObsoleteState = Removed` for a method; that property belongs to supported object and element types.
 
 See sample: `deprecate-public-members-with-the-obsolete-lifecycle.bad.al`.

microsoft/knowledge/breaking-changes/do-not-expose-sensitive-data-through-public-api.good.al

@@ -1,10 +1,10 @@
 codeunit 50320 "Payment Client Good"
 {
     var
-        AccessToken: Text;
+        AccessToken: SecretText;
 
-    // Credential flows inward through an internal setter and never leaves the object.
-    internal procedure SetAccessToken(NewToken: Text)
+    // Credential remains SecretText as it flows inward and is stored.
+    internal procedure SetAccessToken(NewToken: SecretText)
     begin
         AccessToken := NewToken;
     end;

microsoft/knowledge/breaking-changes/do-not-expose-sensitive-data-through-public-api.md

@@ -1,5 +1,5 @@
 ---
-bc-version: [all]
+bc-version: [23..]
 domain: breaking-changes
 keywords: [sensitive-data, secrettext, token, credential, public-api, access-boundary]
 technologies: [al]

microsoft/knowledge/breaking-changes/obsolete-table-fields-instead-of-deleting-them.bad.al

@@ -3,9 +3,9 @@ table 50311 "Customer Profile Bad"
     fields
     {
         field(1; "No."; Code[20]) { }
-        // Breaking: the published "Email" field was renamed in place. Dependent
-        // extensions that reference "Email" stop compiling, and the data stored in
-        // the old column is orphaned on upgrade.
+        // Breaking: the published field was renamed while retaining ID 2.
+        // AppSourceCop AS0005 rejects the compatibility change; retaining the ID
+        // does not by itself mean the stored column was dropped and re-created.
         field(2; "Contact Email"; Text[80]) { }
     }
 }

microsoft/knowledge/breaking-changes/obsolete-table-fields-instead-of-deleting-them.md

@@ -7,20 +7,20 @@ countries: [w1]
 application-area: [all]
 ---
 
-# Obsolete published table fields instead of deleting or renaming them
+# Obsolete published table fields instead of deleting or renumbering them
 
 ## Description
 
-A table field that has shipped carries two contracts at once: extensions reference it by name, and the database holds data in its column. Deleting the field, or renaming it (which the platform treats as drop-plus-add), breaks dependent code at compile time and discards the stored data — a silent data-loss event on upgrade. The fix is the same staged lifecycle used for objects: set `ObsoleteState = Pending` together with `ObsoleteReason` and an `ObsoleteTag` naming the target version, ship the new field alongside, migrate data during the window, and only switch the old field to `ObsoleteState = Removed` in a later release once nothing depends on it. LLMs often "tidy" a schema by renaming a field in place, not realizing this is both a breaking change and a data-loss risk.
+A shipped table field carries both a source-level contract and persisted data. Renaming a field while retaining its ID is prohibited by AppSourceCop AS0005 and can break dependent extensions, but it is not inherently a drop-and-readd operation and should not be described as automatic data loss. Deleting the field or replacing it under a different ID is the data-loss risk: the old field storage is no longer represented unless data is migrated. The supported path is to keep the old field and obsolete it, add a replacement under a new ID, and migrate values before later removal.
 
 ## Best Practice
 
-Add the replacement field, then mark the old field `ObsoleteState = Pending` with an `ObsoleteReason` that names the replacement and an `ObsoleteTag` carrying the target version (for example `'25.0'`). Keep the obsolete field readable so an upgrade codeunit can copy its data into the new field during the deprecation window. Move it to `ObsoleteState = Removed` only in a later major version, after the window has passed and data has migrated.
+Add the replacement field under a new ID, then mark the old field `ObsoleteState = Pending` with an `ObsoleteReason` that names the replacement and an `ObsoleteTag` recording the obsoletion version. Keep the old field readable so an upgrade codeunit can copy its data during the deprecation window. Move it to `ObsoleteState = Removed` only in a later release, after the window has passed and data has migrated.
 
 See sample: `obsolete-table-fields-instead-of-deleting-them.good.al`.
 
 ## Anti Pattern
 
-Renaming the published `Email` field to `Contact Email` directly in the table — or deleting it — so dependent extensions that reference `Email` break and the column's stored values are orphaned on upgrade. Detection: a previously shipped field removed or renamed in a table or table extension with no `ObsoleteState = Pending` step preserving the original. Obsolete the field through the lifecycle instead.
+Renaming published `Email` to `Contact Email` with the same ID violates the compatibility contract and AS0005, even though the retained ID does not itself imply a fresh empty column. Deleting `Email` or moving the replacement to another ID without migration additionally risks losing its stored values. Detection: a previously shipped field removed, renumbered, or renamed with no retained `Pending` field and migration path.
 
 See sample: `obsolete-table-fields-instead-of-deleting-them.bad.al`.