docs(conventions): fix mint-criterion, process and layer-placement drift (#2549, #2550)

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,7 +22,8 @@ Tick the [commit type](https://github.com/JarryShaw/PyPCAPKit/blob/main/CONTRIBU
 - [ ] `ci` — workflows or build tooling
 - [ ] `release` — bumps the version or rolls up a distribution
 - [ ] `chore` — anything else
-- [ ] `const` — regenerates constant or registry tables, members keeping their numeric values
+
+- [ ] Also tick if it regenerates constant or registry tables, members keeping their numeric values (the `const` label)
 
 ---
 

CONTRIBUTING.md

@@ -205,8 +205,9 @@ BLANK LINE
 footer (optional)
 ```
 
-`type` is one of `feat`, `fix`, `docs`, `test`, `perf`, `refactor`, `ci`, `chore`, `release` or
-`const` — those are the ones in use. `scope` names the part of the package affected — `tcp`, `corekit`,
+`type` is one of `feat`, `fix`, `docs`, `test`, `perf`, `refactor`, `ci`, `chore` or `release` —
+those are the ones in use. `const` is not a type: it is a label for regenerated constant tables,
+going on alongside the type label. `scope` names the part of the package affected — `tcp`, `corekit`,
 `schema`, `ipv4`, `vendor` — and several are separated by commas inside the parentheses, as in `fix(link,internet):`
 or `test(utilities,foundation):`. The scope may be omitted where nothing narrower than the whole
 project applies, as in `docs:`.

docs/source/contributing/conventions/mint-criterion.rst

@@ -47,7 +47,7 @@ Measured against the tree, by class:
   **Some of the rest can never reach the call either**, because every range they declare is
   already covered by their own members -- :class:`~pcapkit.const.ipv4.tos_del.ToSDelay`
   declares ``0..1`` and has members ``[0, 1]``, so its ``_unregistered_member`` call is
-  dead code. Those found are :mod:`ipv4.option_class <pcapkit.const.ipv4.option_class>`,
+  dead code. They are :mod:`ipv4.option_class <pcapkit.const.ipv4.option_class>`,
   :mod:`ipv4.tos_del <pcapkit.const.ipv4.tos_del>`,
   :mod:`ipv4.tos_ecn <pcapkit.const.ipv4.tos_ecn>`,
   :mod:`ipv4.tos_pre <pcapkit.const.ipv4.tos_pre>`,
@@ -58,11 +58,7 @@ Measured against the tree, by class:
   :mod:`ipv6.smf_dpd_mode <pcapkit.const.ipv6.smf_dpd_mode>`,
   :mod:`l2tp.type <pcapkit.const.l2tp.type>`,
   :mod:`mh.dhcp_support_mode <pcapkit.const.mh.dhcp_support_mode>` and
-  :mod:`vlan.priority_level <pcapkit.const.vlan.priority_level>`. The ``str``-valued
-  :class:`ftp.command.Command <pcapkit.const.ftp.command.Command>`,
-  :class:`ftp.command.FEATCode <pcapkit.const.ftp.command.FEATCode>` and
-  :class:`http.method.Method <pcapkit.const.http.method.Method>` were not probed, so that
-  list is a floor.
+  :mod:`vlan.priority_level <pcapkit.const.vlan.priority_level>`.
 * **Cache in the value table only**: :class:`~pcapkit.const.tcp.flags.Flags` and the
   Mobility Header flag registries, such as
   :class:`~pcapkit.const.mh.binding_ack_flag.BindingACKFlag`. They range-check and hand
@@ -129,6 +125,15 @@ what the generated code happens to look like:
    bare label stands: suffixing one with a code would **manufacture a name nobody
    assigned**, and the value will get its real name if and when something assigns it.
 
+.. note::
+
+   In the transport registries -- :class:`~pcapkit.const.reg.apptype.tcp.TCP`,
+   :class:`~pcapkit.const.reg.apptype.udp.UDP` and the rest -- the spans IANA assigns
+   to a service are an exception to the first case: ``x11``, ``ircu``, ``swx`` and the
+   others resolve with the bare service name, so ``TCP(6001).name`` is ``'x11'``, not
+   ``'x11_6001'``. Suffixing them would change ``.name``, which a caller can observe.
+   Recorded on :issue:`2550`.
+
 Worked Examples
 ~~~~~~~~~~~~~~~
 

docs/source/contributing/conventions/process.rst

@@ -224,9 +224,13 @@ commit, so the label and the message agree by construction:
      - tooling and repository hygiene, with no library behaviour change
    * - ``release``
      - version bumps and distribution rollups
-   * - ``const``
-     - regenerated IANA or vendor constant tables, members keeping their numeric
-       values
+
+.. note::
+
+   ``const`` is not a type: no commit subject takes a ``const:`` prefix. It marks
+   regenerated IANA or vendor constant tables, members keeping their numeric values,
+   and like ``breaking`` below it is **additive**, going on alongside the type label
+   rather than instead of it.
 
 **Issue kind**, for issues rather than pull requests: ``design`` marks a pattern being
 decided rather than a defect or a request, and a majority of the rulings on these pages

docs/source/contributing/conventions/protocol-layer-placement.rst

@@ -61,8 +61,8 @@ OSI says the same by construction. ITU-T X.200 §9.2.4.4 has a protocol declare
 layer in terms of *"functions which pertain to a particular layer"*, and clause 7
 defines every layer by its purpose rather than by what encapsulates it.
 
-IANA Assignments Carry No Layer Claim
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+IANA Assignments: Encapsulation, Not Layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Every registry this package dispatches on -- *Protocol Numbers*, *Ether Types*,
 and *Service Name and Transport Protocol Port Number* -- has **no layer field**.
@@ -102,8 +102,8 @@ The distinction that dissolves the apparent conflict: computing a forwarding tab
 the **control plane** and makes the protocol a user of the stack; forwarding packets is
 the **data plane** and is internet-layer. OSPF does the former.
 
-Tunnelling Protocols Follow Their Payload
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Tunnelling Protocols: Payload, Not Carrier
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A tunnelling protocol is placed by what it carries, not by what carries it. So
 :class:`~pcapkit.protocols.link.l2tp.L2TP` and

tests/project/test_conventions_doc_claims.py

@@ -1323,9 +1323,12 @@ def test_the_page_names_every_commit_type_the_template_ticks(self) -> 'None':
         The check runs one way, template to page, by design: it would not catch a page
         label gaining no tickbox, only a tickbox naming no label.
 
+        A label that goes on alongside the type, such as ``const``, has an *Also tick
+        if* box outside the type list, so the page has to say it is not a type.
+
         """
-        types = re.findall(r'^- \[ \] `([a-z]+)` ', self.TEMPLATE.read_text(encoding='utf-8'),
-                           re.MULTILINE)
+        text = self.TEMPLATE.read_text(encoding='utf-8')
+        types = re.findall(r'^- \[ \] `([a-z]+)` ', text, re.MULTILINE)
         self.assertGreaterEqual(len(types), 8,
                                 f'only {types!r} parsed out of the pull request '
                                 'template; the check below would pass vacuously')
@@ -1336,6 +1339,19 @@ def test_the_page_names_every_commit_type_the_template_ticks(self) -> 'None':
                               'label, which the pull request template asks every '
                               'contributor to tick')
 
+        additive = re.findall(r'^- \[ \] Also tick if [^`\n]*`([a-z]+)`', text, re.MULTILINE)
+        self.assertTrue(additive,
+                        'no "Also tick if" box parsed out of the pull request '
+                        'template; the check below would pass vacuously')
+        for label in additive:
+            with self.subTest(additive=label):
+                self.assertNotIn(label, types,
+                                 f'the pull request template ticks {label} both as a '
+                                 'commit type and as a label alongside one')
+                self.assertIn(f'``{label}`` is not a type', self.flat,
+                              f'process.rst does not say {label} is not a type, though '
+                              'the pull request template ticks it outside the type list')
+
     def test_the_page_names_what_the_tree_has(self) -> 'None':
         """Every claim the page makes that has local ground truth.