diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f6ff3f0bb1..13fcae42e9 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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) --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24d47a992b..54d6600927 100755 --- a/CONTRIBUTING.md +++ b/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:`. diff --git a/docs/source/contributing/conventions/mint-criterion.rst b/docs/source/contributing/conventions/mint-criterion.rst index 7ad3cca6f9..4b96fd0b3d 100644 --- a/docs/source/contributing/conventions/mint-criterion.rst +++ b/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 `, + dead code. They are :mod:`ipv4.option_class `, :mod:`ipv4.tos_del `, :mod:`ipv4.tos_ecn `, :mod:`ipv4.tos_pre `, @@ -58,11 +58,7 @@ Measured against the tree, by class: :mod:`ipv6.smf_dpd_mode `, :mod:`l2tp.type `, :mod:`mh.dhcp_support_mode ` and - :mod:`vlan.priority_level `. The ``str``-valued - :class:`ftp.command.Command `, - :class:`ftp.command.FEATCode ` and - :class:`http.method.Method ` were not probed, so that - list is a floor. + :mod:`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 ~~~~~~~~~~~~~~~ diff --git a/docs/source/contributing/conventions/process.rst b/docs/source/contributing/conventions/process.rst index 5fbf5a626b..ec7d11f86c 100644 --- a/docs/source/contributing/conventions/process.rst +++ b/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 diff --git a/docs/source/contributing/conventions/protocol-layer-placement.rst b/docs/source/contributing/conventions/protocol-layer-placement.rst index ed81d320e9..7daa114b92 100644 --- a/docs/source/contributing/conventions/protocol-layer-placement.rst +++ b/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 diff --git a/tests/project/test_conventions_doc_claims.py b/tests/project/test_conventions_doc_claims.py index bb0f85d414..71d5cc9d22 100644 --- a/tests/project/test_conventions_doc_claims.py +++ b/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.