This repository was archived by the owner on May 14, 2026. It is now read-only.
docs(dev/guide): more style and contribution guides#255
Merged
Conversation
- Correct push_path/push_back function name mismatch
- Fix non-compiling call sites in the &Path example so the snippet
type-checks against the stated signature
- Add missing `move` and trailing `;` to tokio::task::spawn examples
so they compile
- Rename "Cloning an atomic counter" section to "Cloning `Arc` and `Rc`"
since Arc/Rc are reference counters, not atomic counters
- Fix missing semicolon in an assert_eq! example
- Grammar fixes ("could easily be refactored", "Explicitly marking
the cloned type aids", "as more pull requests are reviewed")
This comment was marked as off-topic.
This comment was marked as off-topic.
This comment was marked as off-topic.
This comment was marked as off-topic.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repository’s Rust code style guide to improve clarity and correctness of examples and wording.
Changes:
- Refines introductory wording and multiple phrasing/grammar issues.
- Fixes/modernizes several Rust snippet examples (e.g.,
async move, semicolons, and parameter passing examples). - Renames the cloning section to more accurately reflect guidance for
Arc/Rc.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Adapted from KSXGitHub/parallel-disk-usage's CONTRIBUTING.md, with pacquet-specific changes: - No version-release exception in the commit message convention - Setup and automated-check sections rewritten around `just init`, `just install`, and `just ready` instead of `test.sh` - Dropped the squashfs/fuse external-dependency section (not relevant to pacquet); kept the registry-mock note instead - Examples reworked to use pacquet types (manifests, store, etc.) - Cross-links between CONTRIBUTING.md and CODE_STYLE_GUIDE.md so the two documents are discovered together AGENTS.md instructs AI agents to follow both guides.
Addresses copilot review comment on PR #255: `push_path` takes `&mut Vec<PathBuf>`, so the call sites need `&mut my_list` rather than `my_list` to compile.
main already has an AGENTS.md (added in #268) with content unrelated to my edits. Removing the duplicate so the merge from main pulls in that file cleanly; the AI-guide references will be re-added on top.
Brings in the AGENTS.md introduced in #268, along with the recent performance, refactor, and benchmark work landed since this branch was started. The local placeholder AGENTS.md was removed in the preceding commit so the merge takes main's version unmodified.
Adds an explicit "Follow the project guides" section near the top of AGENTS.md and lists CONTRIBUTING.md alongside CODE_STYLE_GUIDE.md in the repo-layout overview, so both guides are surfaced as required reading.
KSXGitHub
commented
Apr 25, 2026
Contributor
Author
There was a problem hiding this comment.
Important
The current AGENTS.md technically doesn't follow the added guides regarding the writing styles.
But since I don't want to make the diff too massive and making it harder to review, Claude Code should wait for @zkochan to make the decision.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
…DE.md Per option A of the contributing/style split discussion: keep CONTRIBUTING.md focused on process (commit message format, writing style, setup, automated checks), and have CODE_STYLE_GUIDE.md own every code-level convention. Moved into CODE_STYLE_GUIDE.md (under the existing `## Guides` section, in thematic order): - Module Organization - Import Organization - Derive Macro Ordering - Generic Parameter Naming - Variable and Closure Parameter Naming (with the single-letter rules) - Trait Bounds - Pattern Matching - Using `pipe-trait` (with when-to-use and when-not-to-use) - Error Handling - Conditional Test Skipping (`#[cfg]` vs `#[cfg_attr(..., ignore)]`) - Unit test file layout (was the top-level `## Unit Tests` section) The intra-doc link from "Where the external file sits" to "Module Organization" still resolves because both sections now live in the same file. Updated `AGENTS.md`'s descriptions for both guides to reflect the new split. Per the review thread on this PR, no other prose in `AGENTS.md` was rewritten for writing-style conformance; that is deferred to the maintainer.
The codebase does not follow the rules this section prescribed, so the section was aspirational rather than descriptive of pacquet's actual conventions: - "Split across multiple #[derive(...)] lines" — never done. Across 52 files with derives, zero stack two #[derive(...)] attributes. - Prescribed standard → comparison → Hash → derive_more order — frequently violated. The dominant pattern places Display right after Debug (e.g. crates/lockfile/src/comver.rs:8, crates/lockfile/src/pkg_ver_peer.rs:12). - #[cfg_attr(feature = "...", derive(...))] split — zero occurrences anywhere in crates/. The codebase's actual convention is too loose to codify usefully (one #[derive(...)] line, Debug first when present), so the section is removed rather than weakened to a near-tautology.
KSXGitHub
commented
Apr 25, 2026
The pair was meant to contrast the closure parameter name (`entry` vs. `x`), but using `.filter_map` on the good side and `.filter` on the bad side muddled that with a method-choice difference. The mismatch was carried over from the upstream parallel-disk-usage guide. Use `.filter` on both sides so the example isolates the rule under discussion.
Sweep for the same class of issue as the .filter / .filter_map mismatch (#255, KSXGitHub review): examples that were degraded when ported from upstream parallel-disk-usage. - show_path with `path: &Path`: passing `my_path_buf` directly doesn't compile because `PathBuf` does not auto-coerce to `&Path` in argument position. Use `&my_path_buf` (same fix family as the earlier push_path call sites). - "Avoiding deeply nested function calls": the pre-pipe version was a single non-nested call, so the rule's motivation wasn't visible. Replaced with a genuinely nested constructor chain that piping flattens. - "pipe_as_ref" example lost its contrast in the port; restored the "without pipe" companion line so the rule's payoff is shown. - Picked a custom-looking pacquet function name (is_within_store) for that example instead of `Path::exists`, since nobody uses `path_buf.pipe_as_ref(Path::exists)` over `path_buf.exists()`. - Renamed `rows.zip(cols)` to `left_indices.zip(right_indices)` so the `(i, j)` closure parameters line up with the rule about index variables.
- AGENTS.md: drop the stale "derives" topic from both descriptions of CODE_STYLE_GUIDE.md, since the Derive Macro Ordering section was removed in 06c08ff for not matching the codebase. - AGENTS.md: replace the inaccurate "pre-commit checks" wording in the repo-layout entry for CONTRIBUTING.md. The pre-push hook only runs format checks; the full `just ready` suite is a manual step before submitting, not an automated pre-commit hook. - CODE_STYLE_GUIDE.md: fix subjunctive grammar — "should a test fails" should be "should a test fail" (predates the recent move, but caught while reviewing the section).
…xamples" This reverts commit 0d1e434.
KSXGitHub
commented
Apr 25, 2026
The text says "to pass a reference mid-chain", but the example was a single `path_buf.pipe_as_ref(Path::exists)` call with no chain at all. Replaced with a four-step chain that has methods before and after `pipe_as_ref`, so the rule's wording matches the demonstration. Audited every other pipe example in the section: each one is either already part of a chain (dependencies, into_iter, summarize, etc.) or is intentionally chain-free in the "When NOT to use pipe" section, so no other rectification was needed. Addresses KSXGitHub review on PR #255.
KSXGitHub
commented
Apr 25, 2026
Replace "Install the registry-mock dependencies" with "Install the test dependencies". The previous wording named an internal component (registry-mock) and would drift if `just install` ever did more or different work. The new wording defers to `just install` as the source of truth for what gets installed. Per KSXGitHub review on PR #255.
zkochan
reviewed
Apr 25, 2026
Per @zkochan review on PR #255: reduce the number of alternatives listed for index variables. Keep `index` and `*_index` (such as `row_index`); drop `idx`. Applied to both places where the triple appeared: the "Conventional single-letter names" bullet and the "Index variables" rule, so the two stay consistent.
zkochan
approved these changes
Apr 25, 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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
No description provided.