mirror of
https://github.com/pnpm/pnpm.git
synced 2026-07-28 08:27:30 -04:00
b4310a71b1
* docs: fix bugs and typos in CODE_STYLE_GUIDE.md
- 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")
* docs: add CONTRIBUTING.md and AGENTS.md
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.
* docs: pass &mut my_list in push_path examples
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.
* chore: temporarily remove AGENTS.md before merging main
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.
* docs(agents): point at CONTRIBUTING.md and CODE_STYLE_GUIDE.md
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.
* docs: move code-style sections from CONTRIBUTING.md to CODE_STYLE_GUIDE.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.
* docs(style): drop "Derive Macro Ordering" section
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.
* docs(style): use .filter on both sides of the parameter-naming example
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.
* docs(style): fix four porting quirks in CODE_STYLE_GUIDE.md examples
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.
* docs: address review-agent findings on the docs branch
- 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).
* Revert "docs(style): fix four porting quirks in CODE_STYLE_GUIDE.md examples"
This reverts commit 0d1e4348f0e8f66e552a7d8eb03db701c6fc0fcd.
* docs(style): make the pipe_as_ref example actually mid-chain
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.
* docs(contributing): describe `just install` generically
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.
* docs(style): drop `idx` from the index-naming alternatives
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.
---------
Co-authored-by: Claude <noreply@anthropic.com>