mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 09:26:52 +01:00
Add [all] sentinel to bc-version; apply to version-agnostic knowledge
Most of the corpus — FindSet/SetLoadFields/CalcFields patterns, permission sets, SingleInstance codeunits, DataClassification, IsolatedStorage, transaction scope, SecretText — describes BC platform behaviour that is identical across supported versions. The seed [26..28] range on every file implied a version-specificity the content does not actually have, and there was no way to express "applies to every version" in the schema the way [w1] and [all] already do for countries and application-area. Extend the v1 schema with a universal sentinel for bc-version, parallel to the sentinels already defined for the other dimensions: bc-version: [all] # applies to every BC version [all] is mutually exclusive with explicit versions. Range shorthand ([26..28]) and explicit lists ([26, 27, 28]) continue to work for files genuinely tied to a version-gated API or deprecation. Update read.md (field definition, matching semantics, partial-context rule), write.md (default to [all], use ranges only with a concrete reason), README.md (frontmatter example), and the CI validator. All forty existing knowledge files and the three action skills convert to [all]; none of the current content is version-gated. Validator passes.
This commit is contained in:
parent
23184480d0
commit
9a4198eb28
52 changed files with 68 additions and 58 deletions
|
|
@ -26,7 +26,7 @@ A file that violates any of these rules is invalid and MUST be skipped by consum
|
|||
|
||||
```yaml
|
||||
---
|
||||
bc-version: [26, 27, 28] # or the range shorthand [26..28]
|
||||
bc-version: [all] # or [26, 27, 28] or the range shorthand [26..28]
|
||||
domain: performance
|
||||
keywords: [query, filtering, partial]
|
||||
technologies: [al]
|
||||
|
|
@ -39,12 +39,13 @@ All six fields are required. Missing or empty fields invalidate the file.
|
|||
|
||||
### Fields
|
||||
|
||||
**`bc-version`** — Array. The Business Central major versions this file applies to. Two forms are accepted:
|
||||
**`bc-version`** — Array. The Business Central major versions this file applies to. Three forms are accepted:
|
||||
|
||||
- Universal sentinel: `[all]` means the guidance applies to every BC version and matches any target.
|
||||
- Explicit list: `[26, 27, 28]`.
|
||||
- Range shorthand: `[26..28]` means every integer from 26 through 28 inclusive.
|
||||
|
||||
Consumers MUST expand ranges to the full set before comparison.
|
||||
`[all]` is mutually exclusive with explicit versions; do not combine. Consumers MUST expand ranges to the full set before comparison.
|
||||
|
||||
**`domain`** — String. A single domain tag that places the file within a broader area of concern. Standard values include `performance`, `security`, `ux`, `telemetry`, `testing`, `api`, `pipelines`, `finance`, `supply-chain`, `manufacturing`, `jobs`. New domains may be introduced by contributors; no closed enumeration is enforced at the schema level. Consumers MUST treat unknown domains as valid.
|
||||
|
||||
|
|
@ -93,7 +94,7 @@ Conflict detection is the consumer's responsibility; BCQuality does not enforce
|
|||
|
||||
When a consumer filters or matches files against a task context, these rules apply:
|
||||
|
||||
- **`bc-version`** — the target BC version MUST be an element of the file's expanded `bc-version` set. Range shorthand (`[26..28]`) MUST be expanded before comparison.
|
||||
- **`bc-version`** — the file matches if its set is `[all]`, or if the target BC version is an element of the file's expanded `bc-version` set. Range shorthand (`[26..28]`) MUST be expanded before comparison.
|
||||
- **`technologies`** — non-empty intersection between the task's technologies and the file's technologies. There is no sentinel for this field.
|
||||
- **`countries`** — the file matches if its set contains `w1`, or if there is a non-empty intersection with the task's countries.
|
||||
- **`application-area`** — the file matches if its set contains `all`, or if there is a non-empty intersection with the task's application areas.
|
||||
|
|
@ -104,7 +105,7 @@ A file is **applicable** to a task when all four rules match. Applicability is a
|
|||
|
||||
A task context may omit one or more dimensions (for example, a skill invoked against a raw file path with no known target BC version). For any omitted dimension:
|
||||
|
||||
- If the file's value for that dimension is a universal sentinel (`w1` for countries, `all` for application-area), the rule matches.
|
||||
- If the file's value for that dimension is a universal sentinel (`all` for bc-version, `w1` for countries, `all` for application-area), the rule matches.
|
||||
- Otherwise the rule is treated as **unknown**, not as a match and not as a failure.
|
||||
|
||||
A file with any `unknown` rule is **conditionally applicable**. A consumer MAY include conditionally applicable files in the worklist; if it does, every finding derived from such a file MUST have `confidence` no higher than `medium` and MUST record the unknown dimensions in the finding's `message`. A consumer MAY be configured to exclude conditionally applicable files entirely.
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ Knowledge files do not contain code. Samples live as **sibling files** next to t
|
|||
|
||||
## Choosing frontmatter values
|
||||
|
||||
**`bc-version`.** Claim only the versions you have evidence for. If the guidance is known to apply from BC 24 onward and you have tested against 26–28, write `[26..28]`, not `[24..28]`. Under-claim; a future contributor can widen the range.
|
||||
**`bc-version`.** Default to `[all]` when the guidance is universal — a BC language pattern, a property on a long-standing platform type, a CodeCop rule, or a platform behaviour that has not changed across versions. Use an explicit list or range (`[26, 27, 28]`, `[26..28]`) only when the guidance is tied to a version-gated API, a deprecation, or platform behaviour that genuinely differs across versions. Most knowledge files should be `[all]`; reach for a range only with a concrete reason.
|
||||
|
||||
**`domain`.** Pick one. If two fit, the file is probably two concerns. If no existing domain fits, introduce a new one — domains are open. Prefer existing domains when they are a reasonable fit, to keep retrieval predictable.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue