RULES

   1 ===========================================================================
   2                         1. Naming Rules
   3 ===========================================================================
   4
   5 1-1. "building-blocks" should be the first prefix.
   6
   7 1-2. The top-single block name is "building-blocks"
   8
   9 1-3. Level prefix = "root" | "sub1" | "sub2" | "sub3"
  10         However, using deep down to sub3 is not recommended (WARNING)
  11
  12 1-3-A. Using "sub3" is not recommended (WARNING)
  13
  14 1-4. Except for the top-single block, Level prfix follows
  15         the first prefix.
  16         E.g., "building-blocks-sub1-..."
  17
  18 1-5. For "root" building blocks, the naming rule is:
  19         [first prefix = "building-blocks"]-[level prefix = "root"]-[NAME]
  20         E.g., "building-blocks-root-UI"
  21
  22 1-6. For "sub1" building blocks, which has a "root" building block, "ROOTNAME" as its parent, the naming rule is:
  23         [first prefix]-[level prefix = "sub1"]-[root name = "ROOTNAME"]-[NAME]
  24         E.g., "building-blocks-sub1-UI-wayland"
  25
  26 1-7. For "sub{N}" (N>1) building blocks, which has a "sub{N-1}" building block, "SUB{M}NAME" as its parent at level M (M < N), the naming rule is:
  27         [first prefix]-sub{N}-[root name = "ROOTNAME"]-[sub1 name = "SUB1NAME"]-...-[sub{N-1} name = "SUB{N-1}NAME"]-[NAME]
  28         E.g., "building-blocks-sub2-UI-wayland-core",
  29                 "building-blocks-sub3-UI-wayland-core-extension_super"
  30
  31 1-8. In order to implement "radio-button" UI (choose only one), the block name starts with "chooseonlyone_"
  32         E.g., "building-blocks-root-chooseonlyone_Kernel"
  33         #### CAUTION: NOT SUPPORTED. NOT GUARANTEED TO WORK AS SUPPOSED ####
  34
  35 1-9. [NAME] = [a-zA-Z0-9_]+
  36
  37
  38
  39 ===========================================================================
  40                         2. Relations between blocks
  41 ===========================================================================
  42
  43 2-1. Top block (building-blocks) lists all root-level blocks
  44         Lists with Suggests (optional) and Requires (mandatory)
  45
  46 2-2. A parent block lists all of its direct child blocks (no grandchild listed)
  47         Lists with Suggests (optional) and Requires (mandatory)
  48
  49 2-3. A child block cannot have multiple parents.
  50
  51 2-4. Conflict may be defined between blocks.
  52         However, you need to get consents from all related stake-holders.
  53
  54 2-6. There cannot be any other relations defined between blocks.
  55         Exception: preset and features blocks may Requires/Suggests
  56            other blocks to populate themselves with higher readability.
  57            Refer to RULE 5-4.
  58
  59 2.7. Do not refer to (or declare as a child) a block that does not exist
  60         in this repository.
  61
  62
  63 ===========================================================================
  64         3. Relations between a block and (non-block) packages
  65 ===========================================================================
  66
  67 3-1. A block may include non-block (individual) packages with Requires (mandatory) and Suggests (optional)
  68
  69 3-2. A package (not block) can exist in multiple blocks.
  70
  71 3-3. A package may be not included in any of the blocks
  72         TIC UI will list such packages in "MISC" section.
  73
  74
  75
  76
  77
  78 ===========================================================================
  79                 4. Maintainer and Review Rules
  80 ===========================================================================
  81
  82 4-1. Multiple maintainers (M:) per domain is possible. (limit = 3)
  83
  84 4-2. At least one maintainer per domain
  85
  86 4-3. Please do review in a week for incoming commits after review entry added for the maintainers
  87
  88 4-4. To comitters: add proper maintainers as the reviewers in gerrit.
  89
  90
  91
  92
  93
  94 ===========================================================================
  95                 5. Other Coding Rules
  96 ===========================================================================
  97
  98 5-1. A domain cannot add "BuildRequires"
  99         Global relations cannot be added by an individual domain.
 100
 101 5.2. A domain cannot add "Recommends", "Provides", "Enhances", "Supplements"
 102         We do not have any semantics for building blocks with such relations.
 103         When we have definitions for such semantics and have them implemented in
 104         TIC, we can allow then.
 105
 106 5.3. A block must NOT have any files included
 107
 108 5.4. A block that is not preset/feature cannot add "Requires"/"Suggests" on
 109 another block that is not a direct child of it (ref. RULE 2.6)
 110         E.g., sub2-* cannot Requires/Suggests another root/sub1/sub2
 111         E.g., sub1-A cannot Requires/Suggests sub2-B-X
 112
 113 5.5. A UI Block is a block that cannot be chosen or have relation with other blocks
 114 or packages, but is used to provide UI elements in TIC.
 115
 116     5.5.1. A UI Block has the same naming rule with others.
 117     5.5.2. A block becomes a UI block if it satisfies the following regex:
 118         /__UI__..$/
 119     5.5.3. The last two characters (.. in the regex above) are "tag" that consists of
 120         the placement of the block.
 121         5.5.3.1. Tags are:
 122             BR or br: blank line
 123             HR or hr: <hr>
 124             SD or sd: shaded blank line
 125             SM or sm: summary text is shown (HTML tags works)
 126             HT or ht: HTML tags from summary text is used. (same with SM/sm...)
 127
 128 5.6. Blocks in TIC are placed sorted by package name. (ascending order)
 129
 130 5.7. If the first line of %description starts with __KS_URL__, it denotes for
 131 the model ks file URL to be interpreted by TIC.
 132
 133     5.7.1. Only platform-preset-boards may use such keywords
 134     5.7.2. Only one package with such keyword is effective. If there are two packages
 135         with such keywords are chosen simultaneously, the behavior is "undefined".
 136     5.7.3. The section of "%packages" in the linked ks file is ignored.
 137     5.7.4. If the URL points to a directory index, any ks file in the directory can be
 138         used. (ending with /)
 139
 140 5.8. If the first line of %description starts with __EXPAND__, the block is
 141 expanded in TIC as default
 142
 143     5.8.1. A following word of __EXPAND__ may denote keywords for TIC that
 144         show when to expand and collapse.
 145         e.g., __EXPAND__: TAB1 (expanded with preset tab only)
 146         e.g., __EXPAND__: TAB1_O (expanded with preset tab, collapsed with others)