docs(dev/guide): align guides with enforced perfectionist rules#434
Merged
Conversation
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
perfectionist import_granularity ruleperfectionist rules
perfectionist rulesperfectionist rules
Performance Regression Reportscommit: 2a7a626 --quantity=apparent-size --max-depth=1 --min-ratio=0.01
LogsJSON{
"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
]
}
]
} |
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
perfectionist rules
KSXGitHub
commented
May 29, 2026
perfectionist rules
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
KSXGitHub
commented
May 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
When a
perfectionistrule starts enforcing a convention automatically, the prose that used to describe that convention by hand becomes a duplicate of the rule. The earlierlint!: upgrade perfectionistPR handled this for derive ordering by dropping the redundant quick-reference bullet and reframing the relevantCONTRIBUTING.mdsection 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 installedperfectionistversion.Changes
letbindings. The upgrade in lint: upgradeperfectionist#433 tightenedsingle_letter_let_binding, which no longer permits single-letter bindings for interchangeable test fixtures (hence lint: upgradeperfectionist#433 renamed fixtures such asa/b/c). Remove the now-contradicted "test fixtures with identical roles" exception fromCONTRIBUTING.mdand the AI instruction templates, and require descriptive names forletbindings without the test-code exception.style = "module"in style: switch import granularity from"crate"to"module"#435 meansperfectionist::import_granularitynow enforces import merging automatically. Remove the redundant import bullet from the AI instruction quick reference, and reframe theCONTRIBUTING.mdimport section to lead with automatic enforcement, keeping only the hand-applied convention for platform-gated import blocks.perfectionist0.0.0-rc.17 (the version pinned indylint.toml) and fixed three claims that did not match the rules:short_impl_max_linesknob;single_letter_generichas no configuration.allowed_identstoextra_allowed_idents, the actual field name for the variable and closure rules.i/j/kare exempt as function and closure parameters but not asletbindings, where onlynis 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
mastermerged into it, so it already incorporates #435.https://claude.ai/code/session_01CMrfXtuzxpSbchSJNuwboK