From ec9a5e7aaa108338ee38116aed0474e04dfa3129 Mon Sep 17 00:00:00 2001 From: KOLANICH Date: Tue, 26 Jan 2021 00:06:19 +0300 Subject: [PATCH] Documented `-affected-by` and `-blocked-by` --- user_guide.adoc | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/user_guide.adoc b/user_guide.adoc index 3beb1d6..fb9eb56 100644 --- a/user_guide.adoc +++ b/user_guide.adoc @@ -1589,6 +1589,31 @@ seq: ---- ==== +[[affected-by]] +==== `-affected-by` +Sometimes your spec cannot be implemented optimally because of +missing features and bugs in Kaitai Struct Compiler. You can +leave a machine-readable reference to a bug, so it is possible +to implement a bot, tracking the specs affected, generating reports +and notifying specs authors when the bug affecting them is fixed. + +If the spec cannot be implemented at all because of a bug/missing +feature, you shouldn't use `-affected-by`, instead you should use +`-blocked-by`. It makes sense to track it only in PRs, since we +don't accept broken specs to KSF. + +* Leave just an issue identifier (on GitHub it is just an issue +number, not the internal one, but the one you usually see), +if the bug is in kaitai_struct repo. (The type may be a string +or integer.) +* If the bug is in another repo in kaitai-io, leave a repo +name and an issue number separated by a space. (The type is string.) +* If the bug is in another repo on the same code hosting platform, +prefix repo name with its owner name and a slash. +* If the bug is in a repo on another platform, give its full URI. +* If the issue is affected by multiple bugs, use an array. + + [[verbose-enums]] ==== Verbose enums