mirror of https://github.com/rustfs/rustfs.git synced 2026-07-26 16:28:15 +00:00

Files

T

Zhengchao An d1db9a10cd chore(docs): refresh agent docs, guard doc paths, archive plans (#4203 )

Agent-instruction and architecture docs had drifted from the code:

- CLAUDE.md: slim to commands + pointers; fix wrong claim that
  `make pre-commit` is the full pre-PR gate (that is `make pre-pr`);
  drop stale pre-#3929 file paths and merged bug narratives
- AGENTS.md: drop dead `rust-refactor-helper` skill rule and the
  hand-maintained (already stale) scoped-AGENTS index; link
  architecture docs from Sources of Truth
- .github/AGENTS.md: replace the outdated copied CI command matrix
  with a pointer to ci.yml
- crates/AGENTS.md: merge duplicated Testing sections
- ARCHITECTURE.md: resolve the utils->config contradiction (edges are
  removed), mark volatile counts as snapshots, fix a bad path
- docs/architecture: add README router; move one-shot plans/trackers
  (rebalance-decommission phases, migration-progress ledger, PR
  template) to docs/superpowers/plans with archive headers; fix stale
  source paths in kept inventories (core/sets.rs, core/pools.rs,
  store/mod.rs, startup_* split from #3671)
- docs/operations/tier-ilm-debugging.md: extracted tier debugging
  playbook with corrected paths
- scripts/check_doc_paths.sh: new guard failing pre-commit/pre-pr when
  instruction/architecture docs reference nonexistent file paths
- .claude/skills: add tier-debug and arch-checks repo skills;
  .gitignore now keeps .claude/skills and docs/operations committable

Verification: ./scripts/check_doc_paths.sh,
./scripts/check_architecture_migration_rules.sh (both pass)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

2026-07-02 23:30:13 +08:00

3.9 KiB

Raw Blame History

RustFS Architecture Evolution

This document set tracks the architecture migration from rustfs/backlog#660.

Baseline

Baseline branch: upstream/main
Baseline commit: 61f0dfbc40f748be313be84d834d8259cf3e19c9
Baseline title: fix(ecstore): invalidate wiped disk id cache (#3251)
First migration PR type: docs-only

Core Principle

Cut wrong dependency directions with directories and contracts first, migrate global state in small steps next, and split crates only after boundaries are stable. Storage hot-path behavior must not drift during this migration.

Architecture Documents

runtime-lifecycle.md: runtime, AppContext, startup/readiness, and shutdown contracts.
readiness-matrix.md: request-surface behavior, runtime dependency readiness, probe semantics, and preservation rules.
s3-tables-support-matrix.md: supported, preview, reference-only, and not-claimed S3 Tables and Iceberg REST Catalog surfaces.
storage-control-data-plane.md: boundaries between StorageCore, ECStore, ClusterControlPlane, and BackgroundControllers.
background-services-inventory.md: current scanner, heal, lifecycle, replication, config reload, metrics, and shutdown surface before BackgroundController work.
background-controller-contract.md: desired/current/status/reconcile vocabulary and lifecycle boundaries for future read-only BackgroundController work.
crate-boundaries.md: PR types, crate direction, compatibility rules, and migration guardrails.
global-state-crate-split-plan.md: late global-state cleanup, runtime-source boundaries, fallback removal rules, and crate-split evaluation criteria.
obs-ecstore-dependency-inventory.md: observability-to-ECStore dependency inventory, classification, and extraction guardrails.
ecstore-config-consumer-inventory.md: current ecstore::config::{Config, KV, KVS} definitions, consumers, migration risks, and do-not-change contract.
ecstore-api-facade-inventory.md: current rustfs_ecstore::api facade groups, external consumer boundaries, shrink rules, and split dependency inventory.
config-model-boundary-adr.md: target crate, module path, dependency rules, and verification gates for moving the pure server-config model.
migration-progress.md: historical task ledger for the closed migration (execution tracking moved to issue #665).
compat-cleanup-register.md: temporary compatibility code that must be removed later.

Phase Order

flowchart LR
    G["Phase 0: Baseline and guardrails"]
    CFG["Phase 1a: Config model contract"]
    SEC["Phase 1: Security governance"]
    API["Phase 2: Storage API contracts"]
    RT["Phase 3: Runtime and lifecycle"]
    EC["Phase 4: ECStore internal layout"]
    CP["Phase 5: Cluster control plane"]
    EXT["Phase 6: Extension plane"]
    GS["Phase 7: Global-state reduction"]
    CR["Crate split evaluation"]

    G --> CFG
    G --> SEC
    G --> API
    G --> RT
    CFG --> EXT
    API --> EC
    RT --> GS
    EC --> CP
    EXT --> CR
    GS --> CR

The first implementation sequence is conservative:

Record baseline and migration context.
Establish PR and compatibility rules.
Add dependency and loss-prevention checks in a separate ci-gate PR.
Inventory ecstore::config::{Config, KV, KVS} before moving any code.
Decide the config model boundary before extracting or migrating consumers.

3.9 KiB Raw Blame History