Skip to content

docs(dev/guide): align guides with enforced perfectionist rules#434

Merged
KSXGitHub merged 7 commits into
masterfrom
claude/clever-knuth-ZQTFF
May 29, 2026
Merged

docs(dev/guide): align guides with enforced perfectionist rules#434
KSXGitHub merged 7 commits into
masterfrom
claude/clever-knuth-ZQTFF

Conversation

@KSXGitHub

@KSXGitHub KSXGitHub commented May 29, 2026

Copy link
Copy Markdown
Owner

When a perfectionist rule starts enforcing a convention automatically, the prose that used to describe that convention by hand becomes a duplicate of the rule. The earlier lint!: upgrade perfectionist PR handled this for derive ordering by dropping the redundant quick-reference bullet and reframing the relevant CONTRIBUTING.md section as automatically enforced. This PR applies the same treatment to conventions that recent upgrades left duplicated, and corrects rule references that did not match the installed perfectionist version.

Changes

  • Single-letter let bindings. The upgrade in lint: upgrade perfectionist #433 tightened single_letter_let_binding, which no longer permits single-letter bindings for interchangeable test fixtures (hence lint: upgrade perfectionist #433 renamed fixtures such as a/b/c). Remove the now-contradicted "test fixtures with identical roles" exception from CONTRIBUTING.md and the AI instruction templates, and require descriptive names for let bindings without the test-code exception.
  • Import granularity. The switch to style = "module" in style: switch import granularity from "crate" to "module" #435 means perfectionist::import_granularity now enforces import merging automatically. Remove the redundant import bullet from the AI instruction quick reference, and reframe the CONTRIBUTING.md import section to lead with automatic enforcement, keeping only the hand-applied convention for platform-gated import blocks.
  • Correct inaccurate rule references. Verified the single-letter guidance against perfectionist 0.0.0-rc.17 (the version pinned in dylint.toml) and fixed three claims that did not match the rules:
    • Removed the fabricated short_impl_max_lines knob; single_letter_generic has no configuration.
    • Renamed allowed_idents to extra_allowed_idents, the actual field name for the variable and closure rules.
    • Clarified that i/j/k are exempt as function and closure parameters but not as let bindings, where only n is allowed.

The AI instruction files (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) are regenerated from the templates via ./run.sh pdu-ai-instructions --generate ..

This branch has master merged into it, so it already incorporates #435.

https://claude.ai/code/session_01CMrfXtuzxpSbchSJNuwboK

Mirror the markdown guide updates from the previous `perfectionist`
upgrade. The upgrade in #433 added the
`perfectionist::import_granularity` rule, which now enforces merged
imports automatically. Document this in CONTRIBUTING.md and drop the
now-redundant manual bullet from the AI instruction templates.

https://claude.ai/code/session_01CMrfXtuzxpSbchSJNuwboK
@KSXGitHub KSXGitHub changed the title docs: update guides for perfectionist import_granularity rule docs: update guides for perfectionist rules May 29, 2026
@KSXGitHub KSXGitHub changed the title docs: update guides for perfectionist rules docs(dev/guide): update guides for perfectionist rules May 29, 2026
@github-actions

github-actions Bot commented May 29, 2026

Copy link
Copy Markdown

Performance Regression Reports

commit: 2a7a626

--quantity=apparent-size --max-depth=1 --min-ratio=0.01
Command Mean [ms] Min [ms] Max [ms] Relative
pdu 100.9 ± 17.6 84.9 154.3 1.18 ± 0.21
pdu-0.20.0 85.6 ± 0.6 84.9 87.7 1.00
Logs
Benchmark 1: pdu
  Time (mean ± σ):     100.9 ms ±  17.6 ms    [User: 55.1 ms, System: 282.7 ms]
  Range (min … max):    84.9 ms … 154.3 ms    29 runs
 
Benchmark 2: pdu-0.20.0
  Time (mean ± σ):      85.6 ms ±   0.6 ms    [User: 55.2 ms, System: 279.1 ms]
  Range (min … max):    84.9 ms …  87.7 ms    34 runs
 
Summary
  pdu-0.20.0 ran
    1.18 ± 0.21 times faster than pdu
JSON
{
  "results": [
    {
      "command": "pdu",
      "mean": 0.1008734803048276,
      "stddev": 0.017639451008228137,
      "median": 0.09916945696000001,
      "user": 0.055107864137931034,
      "system": 0.2827195434482758,
      "min": 0.08493941396000002,
      "max": 0.15427975396000002,
      "times": [
        0.10261405596,
        0.12210469596000001,
        0.11252412596,
        0.11184487496000001,
        0.14975081596,
        0.15427975396000002,
        0.11509657896,
        0.10995204096,
        0.08554934796,
        0.10153692796,
        0.10088569696,
        0.10197052396,
        0.10176431996000002,
        0.09670380396,
        0.09853213196000002,
        0.09766433796000001,
        0.09622937196,
        0.09916945696000001,
        0.09954436296,
        0.09974350396000001,
        0.08556088996,
        0.08590367696000001,
        0.08499553896,
        0.08552907096000001,
        0.08498976796000002,
        0.08509868096,
        0.08493941396000002,
        0.08556735196000001,
        0.08528580796000002
      ],
      "exit_codes": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    {
      "command": "pdu-0.20.0",
      "mean": 0.08563294431294119,
      "stddev": 0.0006428967138495859,
      "median": 0.08552663146,
      "user": 0.05516858117647059,
      "system": 0.2790961164705882,
      "min": 0.08492636996,
      "max": 0.08768433696,
      "times": [
        0.08579889196000001,
        0.08611321696000002,
        0.08595711596,
        0.08498034096000001,
        0.08504099296,
        0.08518460996000002,
        0.08611562096,
        0.08768433696,
        0.08556165196000001,
        0.08548947696,
        0.08675419796,
        0.08492636996,
        0.08521176996000002,
        0.08507214096000001,
        0.08570656096000001,
        0.08512339696000001,
        0.08507123996000002,
        0.08498112196000002,
        0.08579067696,
        0.08569913696,
        0.08602661596,
        0.08588306896,
        0.08559159696000002,
        0.08700971296000001,
        0.08521758196000001,
        0.08642853296,
        0.08492890496,
        0.08521912396,
        0.08501899196000001,
        0.08591048996,
        0.08549161095999999,
        0.08528806296,
        0.08605079996000001,
        0.08519214396
      ],
      "exit_codes": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  ]
}

claude added 2 commits May 29, 2026 14:27
The `perfectionist` upgrade in #433 tightened the
`single_letter_let_binding` rule, which no longer permits single-letter
`let` bindings for interchangeable test fixtures. That leeway was the
reason #433 renamed fixtures such as `a`/`b`/`c` to descriptive names.

Remove the now-contradicted test-fixtures exception from CONTRIBUTING.md
and the AI instruction templates, and state that `let` bindings must use
descriptive names in test code as well as non-test code.

https://claude.ai/code/session_01CMrfXtuzxpSbchSJNuwboK
Reconcile with the import-granularity switch to `module` (#435), which
supersedes this branch's interim `crate`-granularity documentation. The
single-letter test-fixtures guidance fix is retained.

# Conflicts:
#	.github/copilot-instructions.md
#	AGENTS.md
#	CLAUDE.md
#	CONTRIBUTING.md
#	template/ai-instructions/shared.md
@KSXGitHub KSXGitHub changed the title docs(dev/guide): update guides for perfectionist rules docs(dev/guide): drop the single-letter test-fixtures exception May 29, 2026
Comment thread CONTRIBUTING.md Outdated
@KSXGitHub KSXGitHub changed the title docs(dev/guide): drop the single-letter test-fixtures exception docs(dev/guide): align guides with enforced perfectionist rules May 29, 2026
claude added 2 commits May 29, 2026 15:20
Now that `perfectionist::import_granularity` (`style = "module"`)
enforces import merging automatically, the prose that described how to
merge imports merely restated the rule. Apply the same treatment the
earlier `perfectionist` upgrade gave to derive ordering: drop the
redundant import bullet from the AI instruction quick reference, and
reframe the CONTRIBUTING.md section to lead with automatic enforcement,
keeping only the hand-applied convention for platform-gated import
blocks.

https://claude.ai/code/session_01CMrfXtuzxpSbchSJNuwboK
Verified the guidance against `perfectionist` 0.0.0-rc.17 and corrected
three claims that did not match the rules:

- Remove the fabricated `short_impl_max_lines` knob from the generic
  naming section. The `single_letter_generic` rule has no configuration;
  canonical cases are silenced site-by-site with `#[allow]` or
  `#[expect]`.
- Rename the `allowed_idents` knob to `extra_allowed_idents`, which is
  the actual field name for the variable and closure rules.
- Clarify that `i`/`j`/`k` are exempt as function and closure parameters
  but not as `let` bindings, where only `n` is allowed.

https://claude.ai/code/session_01CMrfXtuzxpSbchSJNuwboK
Comment thread CONTRIBUTING.md Outdated
@KSXGitHub KSXGitHub marked this pull request as ready for review May 29, 2026 17:04
@KSXGitHub KSXGitHub merged commit 2bcd85a into master May 29, 2026
14 of 15 checks passed
@KSXGitHub KSXGitHub deleted the claude/clever-knuth-ZQTFF branch May 29, 2026 17:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants