Zoltan Kochan
5d366c3f27
Extend PHILOSOPHY.md, pnpr/AGENTS.md, REVIEW_GUIDE.md, .coderabbit.yaml, and .pr_agent.toml so the repository philosophy applies to pnpr and establishes that pnpr is pre-1.0 on the alpha prerelease lane (experimental per PHILOSOPHY.md), consolidating storage layouts, internal record formats, configuration keys, and CLI flags in place before 1.0 without backward-compatibility fallbacks, aliases, or migration commands between alpha builds. - Remove pnpr upgrade-storage and Command::UpgradeStorage. - Remove legacy .pnpr-journal recovery path and journal manifest serde aliases (packument_file, tarballs). - Remove StoredDerivedTar::Legacy and DerivedTar::scanned in .tar-integrity records. - Remove the redundant /v1 segment from compiler_cache_path. - Remove CLI subcommand and flag aliases (pnpr config-check, --packument-ttl-secs, --no-check-hashes, --min-age-secs, --max-age-secs) and the PNPR_PACKUMENT_TTL_SECS env fallback. - Remove YAML configuration snake_case, *_secs, maxage, and backend.postgresql serde aliases, standardizing on camelCase.
2.8 KiB
pnpm project philosophy
This philosophy applies across the repository, including the pnpm CLI and the
pnpr registry server.
Core requirements
Security, performance, efficient disk usage, and predictability are core requirements. Design for them together. Look for a design that preserves all four before accepting a tradeoff.
For example, lockfile verification can retain a secure default while caching verification work for fast installs. An explicit option to trust the lockfile lets users choose speed when their environment provides other security checks. When a tradeoff remains, provide explicit options that let users choose for their environment. Keep secure behavior as the default and make each option's behavior predictable.
Features and abstractions
First assess whether existing pnpm or pnpr capabilities, alone or in
combination, solve the user's problem. Reuse them when they do. Extend the
owning capability when it leaves a gap and the extension fits the overall
architecture.
A feature expected to be widely used can justify added complexity. Evaluate how that complexity changes the whole system: a broader abstraction can make older features simpler by expressing them as cases of the new model. Favor that consolidation over accumulating independent special cases. Prioritize code reuse and deduplication, while preserving meaningful differences in behavior.
Compatibility can delay consolidation of stable features until the next major version. Temporary duplication is acceptable until then, with the intended shared abstraction and consolidation point identified. Experimental features can be consolidated immediately.
Compatibility and releases
Breaking changes to stable behavior require a major version bump. Experimental
areas can change before the next major release. Apply this exception only when
project documentation, release notes, or feature metadata explicitly identifies
the affected feature as experimental. Treat areas without that designation as
stable; novelty or implementation language alone does not make them experimental.
pnpr is pre-1.0 on the alpha prerelease lane, so its storage layout,
internal formats, configuration, and CLI or HTTP surfaces are experimental.
Consolidate them in place before 1.0.
npm compatibility is useful evidence, not a requirement. pnpm and pnpr can
choose their own behavior for a clear reason. Agreement among several
alternative package managers or registries is a signal to consider following
their approach, but cannot override the core requirements.
Concrete benefits
Evaluate ease-of-use claims through concrete benefits, such as fewer steps for a common task or clearer recovery from an error. Ease of use is subjective and does not replace evidence of value or override the core requirements.