docs(const,vendor): state the generated files' rulings instead of quoting them - #996
Conversation
JarryShaw
added
const
6709fb3 to
56bd6cf
Compare
|
NEEDS CHANGES at #877 revised twice, and the prose stated the middle revision. The passage kept case-insensitivity to selected registries "where it logically makes sense or where the RFC itself treats the names as case-insensitive" — a faithful rendering of the 02:30:58Z redaction, except that the thread runs on. At 02:48:29Z the maintainer reissues it RFC-directed: case-insensitive where the RFC states the values are, case-sensitive otherwise, recorded as final at 02:51:38Z. That limb is not in the ruling, so it is out of both halves of the pair. Two cosmetic items alongside it — the re-flow had wrapped a Four corrections to my own account, two of them to things I published in the commit message.
Re-verified at One item this change does not touch, for the record: |
…ting them The last tranche of #987, plus #995. These files are generated, so every change is made twice: in the vendor template and identically in the const file it renders. The template holds the prose verbatim with {NAME}/{DOCS} placeholders, so the next crawler run reproduces it. No crawler was run. Scope: 22 italic-quoted spans across 7 files, of which 16 are rulings and converted. Six are not and stay -- all of them RFC 5797 and RFC 2389 text on FEAT-code case sensitivity. The italic pattern also missed 14 straight-quoted spans in the apptype pair, 7 per side, most wrapping a backticked vertical bar; those are converted too. - #877 was revised twice and the prose stated the middle revision. The final ruling is RFC-directed: an enum treats its values as case-insensitive where the RFC states they are, and as case-sensitive otherwise. The earlier form, which also allowed a fold where it logically made sense, is out. - #860's ruling is narrowed to what it says. The prose called it the ruling for the whole family, but the comment reads "for all three" and names FEATCode, Command and Method. AppType is never named in it, and the AppType work is #874 under #860, so the prose now says the family follows a ruling given for those three rather than that it was given for the family. - #860's FEAT-value question was answered conditionally, on whether it matched the approach already in use; that conditional is restored. - The #921 exception ruling had lost its second clause -- that the exception comes from pcapkit.utilities.exceptions rather than being a builtin. - #995: vendor/ipx/socket.py credited a ruling with "a real ownership fact", which is in no maintainer comment. The real reason, #847 at 13:15:36Z, is that a proprietary protocol may expose no name of its own. That comment is module documentation for UNASSIGNED_RANGE_NAMES and is not emitted into the const file, so only the template changed. - The exception ruling was credited to issue #923, which carries no maintainer comment at all -- its own body attributes the ruling to the review of #877's implementation. So the prose now credits the ruling to that review and #923 with the implementation, keeping the citation in issue form as docs/source/contributing/conventions/documentation.rst requires. - Re-flowing wrapped one inline literal that the base had whole, and left five orphan tails. All six are closed. Prose only, and proven against the one risk that matters in a generated file. Importing both trees gives a byte-identical sha256 over every name and value for the seven enums the three touched const files define -- 127 members, 126 iterable -- and the generated rST table rows are identical at 603 distinct of 707. Token sequences match per file with comments and NL dropped, masking FSTRING_MIDDLE as well as STRING since the templates are f-strings and their prose tokenises as the former. The over-95 line set is unchanged in every file. Closes #995.
56bd6cf to
95c1182
Compare
|
Round 2: GOOD TO GO at Its one nit was this pull request's own defect class, so it is fixed rather than shipped. New head But #921 is a pull request, and Re-verified at |
|
Round 3: GOOD TO GO at It settled the one thing I had flagged as unchecked. Every Re-derived at this head rather than carried over: all seven files token-identical to It declared two checks UNVERIFIED and was right to — it did not re-run the import hash or the row extraction, neither of which a change confined to one docstring paragraph can reach. I ran both myself at Label is now |
JarryShaw
added
review: good-to-go
|
One citation note, and a deliberate decision not to amend for it. The commit message and this description cite "#847 at 13:15:36Z" as the source of the ownership ruling. #847 is a pull request ( The shipped prose is unaffected — So I am leaving it: amending would invalidate a verdict already given at |
|
Ready to merge at One commit, prose only, on top of the current Unpublished decisions are yours, and I have not merged. Two things queued behind this one, both deliberately: #987's last residual is fixed and verified but unpushed, because main's ruleset has |
JarryShaw
removed
the
review: good-to-go
1 participant
Please follow the guide below
make pylint,make mypy,make isort)make testpasses, and a test case covers the changedocs/source/changelog/and regeneratedCHANGELOG.md, if the change is user-visible — N/A, centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657What is the purpose of your pull request?
fix— corrects a defectfeat— adds a featureperf— changes performance, not behaviourrefactor— changes neither behaviour nor performancetest— tests onlydocs— documentation onlyci— workflows or build toolingchore— anything elseCloses #995.
Description of your pull request and other information
The last tranche of #987, plus #995. These files are generated, so every change is made twice — in the vendor template and identically in the const file it renders. The template holds the prose with
{NAME}/{DOCS}placeholders, so the next crawler run reproduces it. No crawler was run; they need the network and thevendorextra.Scope. 22 italic-quoted spans across 7 files, of which 16 are rulings and are converted. Six are not and stay — all of them RFC 5797 and RFC 2389 text on FEAT-code case sensitivity. The italic pattern also missed 14 straight-quoted spans in the apptype pair, 7 per side, most wrapping a backticked vertical bar; those are converted too.
#877 was revised twice, and this pull request's first revision rendered the middle one. The final ruling is RFC-directed: an enum treats its values as case-insensitive where the RFC states they are, and as case-sensitive otherwise. The earlier form, which also allowed a fold where it logically made sense, is out of both halves of the ftp pair.
#860's ruling is narrowed to what it actually says. The prose called it the ruling for the whole family. The comment reads "for all three" and names
FEATCode,CommandandMethod;AppTypeis never named in it, and theAppTypework is #874 under #860. So the prose now says the family follows a ruling given for those three. One flattened conditional is restored — #860's FEAT-value question was answered conditionally, on whether it matched the approach already in use — and one lost clause: the #921 exception ruling also says the exception comes frompcapkit.utilities.exceptionsrather than being a builtin.#995:
vendor/ipx/socket.pycredited a ruling with "a real ownership fact", which appears in no maintainer comment. The real reason, #847 at 13:15:36Z, is that a proprietary protocol may expose no name of its own. That#:block is module documentation forUNASSIGNED_RANGE_NAMESand is not emitted into the const file, so only the template changed.Prose only, proven against the one risk that matters in a generated file. A sha256 over every name and value is byte-identical between the two trees for the seven enums the three touched const files define — 127 members, 126 iterable.
AppTypeis a runtime registry and contributes none of them, so its generated reStructuredText rows are checked separately: identical at 603 distinct of 707. Token sequences match per file with comments andNLdropped, maskingFSTRING_MIDDLEas well asSTRING, since the templates are f-strings and their prose tokenises as the former. The over-95 line multiset is unchanged in every file, and six wrapping warts the re-flow introduced — one split inline literal and five orphan tails — are closed.Two things left for later, both outside this tranche: the same phrase survives in
tests/vendor/test_ipx_socket_unit.pyand intests/const/test_const_enum_no_mint.py, and a further set of italic spans underpcapkit/protocols/were not examined — 25 by my own multi-line-aware extraction against the worker's 26, a one-span discrepancy the follow-up reconciles. 23 of the 25 wrap across lines, which is why a single-line regex finds only two, and every one sampled is RFC text rather than a ruling.