Skip to content
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
zkochan merged 15 commits into
mainfrom
claude/review-code-style-guide-zn4BH
Apr 25, 2026
Merged

docs(dev/guide): more style and contribution guides#255
zkochan merged 15 commits into
mainfrom
claude/review-code-style-guide-zn4BH

Conversation

@KSXGitHub

Copy link
Copy Markdown
Contributor

No description provided.

- 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")
@github-actions

This comment was marked as off-topic.

@github-actions

This comment was marked as off-topic.

@KSXGitHub KSXGitHub requested a review from zkochan April 24, 2026 09:17
@KSXGitHub KSXGitHub marked this pull request as ready for review April 24, 2026 09:17
@zkochan zkochan requested a review from Copilot April 24, 2026 10:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread CODE_STYLE_GUIDE.md Outdated
@KSXGitHub KSXGitHub marked this pull request as draft April 25, 2026 13:24
@KSXGitHub KSXGitHub changed the title docs(code-style): fix docs(dev/guide): add and renovate Apr 25, 2026
claude added 5 commits April 25, 2026 13:34
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 KSXGitHub changed the title docs(dev/guide): add and renovate docs(dev/guide): fix, add, and renovate Apr 25, 2026
@KSXGitHub KSXGitHub changed the title docs(dev/guide): fix, add, and renovate docs(dev/guide): more style and contribution guides Apr 25, 2026
Comment thread AGENTS.md

@KSXGitHub KSXGitHub Apr 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

claude added 2 commits April 25, 2026 14:33
…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.
Comment thread CODE_STYLE_GUIDE.md
claude added 4 commits April 25, 2026 14:46
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).
Comment thread CODE_STYLE_GUIDE.md
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 KSXGitHub marked this pull request as ready for review April 25, 2026 15:08
Comment thread CONTRIBUTING.md Outdated
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.
Comment thread CODE_STYLE_GUIDE.md Outdated
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 zkochan merged commit 9a59fc7 into main Apr 25, 2026
@zkochan zkochan deleted the claude/review-code-style-guide-zn4BH branch April 25, 2026 19:47
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants