From c0e63ee5435da328268d7fab4880642b81545a34 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 3 Oct 2026 21:30:26 +0800 Subject: [PATCH] docs: trim redundant project skills (#8323) --- .agents/references/implementation.md | 7 + .../references/concurrency-durability.md | 8 +- .../references/correctness.md | 2 + .../references/test-coverage.md | 3 +- .../skills/code-change-verification/SKILL.md | 51 ----- .../agents/openai.yaml | 4 - .agents/skills/issue-triage/SKILL.md | 113 +---------- .agents/skills/pr-review/SKILL.md | 99 ++-------- .agents/skills/rust-code-quality/SKILL.md | 116 ----------- .../skills/rustfs-logging-governance/SKILL.md | 34 ---- .../agents/openai.yaml | 4 - .../skills/rustfs-release-publish/SKILL.md | 184 +++--------------- .../references/final-release.md | 22 +++ .../references/preview-release.md | 24 +++ .../references/release-candidate.md | 37 ++++ .../rustfs-release-version-bump/SKILL.md | 122 ++---------- .../skills/test-coverage-improver/SKILL.md | 57 ------ .../test-coverage-improver/agents/openai.yaml | 4 - .../references/coverage-prioritization.md | 25 --- AGENTS.md | 16 +- docs/README.md | 3 + .../architecture-guard-troubleshooting.md | 6 +- .../operations}/logging-governance.md | 1 + docs/testing/README.md | 3 + scripts/README.md | 2 +- 25 files changed, 183 insertions(+), 764 deletions(-) delete mode 100644 .agents/skills/code-change-verification/SKILL.md delete mode 100644 .agents/skills/code-change-verification/agents/openai.yaml delete mode 100644 .agents/skills/rust-code-quality/SKILL.md delete mode 100644 .agents/skills/rustfs-logging-governance/SKILL.md delete mode 100644 .agents/skills/rustfs-logging-governance/agents/openai.yaml create mode 100644 .agents/skills/rustfs-release-publish/references/final-release.md create mode 100644 .agents/skills/rustfs-release-publish/references/preview-release.md create mode 100644 .agents/skills/rustfs-release-publish/references/release-candidate.md delete mode 100644 .agents/skills/test-coverage-improver/SKILL.md delete mode 100644 .agents/skills/test-coverage-improver/agents/openai.yaml delete mode 100644 .agents/skills/test-coverage-improver/references/coverage-prioritization.md rename .agents/skills/arch-checks/SKILL.md => docs/operations/architecture-guard-troubleshooting.md (89%) rename {.agents/skills/rustfs-logging-governance/references => docs/operations}/logging-governance.md (96%) diff --git a/.agents/references/implementation.md b/.agents/references/implementation.md index 4367b7862..67695c27a 100644 --- a/.agents/references/implementation.md +++ b/.agents/references/implementation.md @@ -58,6 +58,13 @@ are repository-relative. Read only the relevant sections during read-only review - Attach error context once where it is actionable. Do not erase typed errors below aggregation or quorum layers. +## Rust Boundaries + +- Production `unwrap`/`expect` must follow a type guarantee or checked invariant; explain only non-obvious guarantees. +- Public APIs do not return `Result<_, String>`. Library APIs use domain errors unless intentional erasure is part of the boundary contract; expose a stored inner error through `Error::source()`. +- Numeric conversions must not silently truncate. Use fallible conversions for untrusted values; validate finiteness, sign, and range before float-to-integer conversion. Clamp/saturate only when required by the domain. +- Do not add crate-root `#![allow(dead_code)]`. + ## Naming Use Rust API naming: `SCREAMING_SNAKE_CASE` constants/statics, `snake_case` diff --git a/.agents/skills/adversarial-validation/references/concurrency-durability.md b/.agents/skills/adversarial-validation/references/concurrency-durability.md index ae09a7718..d15e38585 100644 --- a/.agents/skills/adversarial-validation/references/concurrency-durability.md +++ b/.agents/skills/adversarial-validation/references/concurrency-durability.md @@ -2,8 +2,12 @@ - For every changed lock, enumerate overlapping lock sets and construct the ABBA interleaving. Multiple-lock order must be documented and consistent. -- Mark guard lifetimes and every `.await`, disk, and RPC call inside them. - Estimate contention and timeout behavior under concurrent requests. +- Mark guard lifetimes and every `.await`, disk, + and RPC call; estimate contention/timeouts. Tokio read/write guards across + `.await` need bounded hold time; long-lived reads can wedge writers (#4195). + Keep `std::sync::Mutex` holds brief and never across `.await`. +- Use direct `fetch_*` for unconditional atomic read-modify-write and + `compare_exchange` for conditional updates. - Object commits remain fenced if the distributed lock is lost after shard writes and before metadata rename. - For write/rename changes, trace `write tmp -> sync tmp -> rename -> sync parent diff --git a/.agents/skills/adversarial-validation/references/correctness.md b/.agents/skills/adversarial-validation/references/correctness.md index 05b3d95f6..475ef553b 100644 --- a/.agents/skills/adversarial-validation/references/correctness.md +++ b/.agents/skills/adversarial-validation/references/correctness.md @@ -15,6 +15,8 @@ Attack the changed behavior, not every subsystem in the repository. bytes and length. - For multipart/object commits, fail before/after rename and cleanup; committed data must remain readable and pre-commit cleanup must not destroy parts. +- Bound recursion over untrusted or persisted input; handle corrupted/cyclic + tree and cache traversals safely. - For version/index ordering, test `len - 1`, `len`, equal timestamps, missing versions, and deterministic tie-breaking. - For directory-object behavior, trace `__XLDIR__` at the store layer; branches diff --git a/.agents/skills/adversarial-validation/references/test-coverage.md b/.agents/skills/adversarial-validation/references/test-coverage.md index 4c193bcd1..cd11adeeb 100644 --- a/.agents/skills/adversarial-validation/references/test-coverage.md +++ b/.agents/skills/adversarial-validation/references/test-coverage.md @@ -19,7 +19,8 @@ serialization is required. - Internal metadata tests assert both RustFS and MinIO keys, not only read-back through a helper that prefers one key. -- Boundary companions are distinct coverage: `n == max` vs `max + 1`, and +- Avoid duplicate tests of the same production path and poison-value class. + Boundary companions are distinct coverage: `n == max` vs `max + 1`, and absent vs empty vs nil UUID. - A focused test proves only the targets/features it builds. Add compilation or Clippy only for uncovered changed targets. diff --git a/.agents/skills/code-change-verification/SKILL.md b/.agents/skills/code-change-verification/SKILL.md deleted file mode 100644 index 3f91fabb5..000000000 --- a/.agents/skills/code-change-verification/SKILL.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: code-change-verification -description: Review a commit, PR, or merged patch when the user requests ordinary code-change verification. Do not combine with adversarial-validation; use that skill instead for explicitly adversarial, substantial, or high-risk RustFS reviews. ---- - -# Code Change Verification - -Use this skill for an ordinary requested review. If the root policy or user calls -for adversarial validation, use `adversarial-validation` instead of running both. - -## Core Workflow - -### 1) Scope and assumptions -- Derive the change source, target branch, and relevant runtime/version from the - supplied diff and metadata. Ask only when missing context could change the verdict. -- Focus only on requested scope; avoid reviewing unrelated files. - -### 2) Risk map -- Prioritize in this order: - - Data correctness and user-visible behavior - - API/contract compatibility - - Security and authz/authn boundaries - - Concurrency and lifecycle correctness - - Performance and resource usage -- Give higher priority to stateful paths, migration logic, defaults, and error handling. - -### 3) Evidence-based inspection -- Read each modified hunk with neighboring context. -- Trace call paths and call-site expectations. -- Check for: - - invariant breaks and missing guards - - unchecked assumptions and null/empty/error-path handling - - stale tests, fixtures, and configs - - hidden coupling to shared helpers/constants/features -- Apply root `AGENTS.md`'s finding standard: try to disprove a candidate before - reporting it. Mention an unresolved question only when it could materially - change the verdict; do not fill the report with speculative possibilities. - -#### Rust-specific checks - -For changed Rust behavior, use the matching sections of [rust-code-quality](../rust-code-quality/SKILL.md). Reuse checks already performed by the selected review workflow. Comment-only or formatting-only Rust diffs do not require the full Rust checklist. Carry its P0–P3 ratings over unchanged and use this skill's output format. - -### 4) Findings-first output -- Order supported findings by P0–P3 severity; preserve the Rust ratings above. - Include `path:line`, the failure and impact, a focused fix, and its validation. -- If no supported issues remain, state `No findings` with the reviewed scope and - any material verification limitation. Do not append optional improvements to - make a clean review look productive. - -Close after the required review. Recommend additional verification only for an -identified unresolved risk or required gate; reuse evidence for unchanged code. diff --git a/.agents/skills/code-change-verification/agents/openai.yaml b/.agents/skills/code-change-verification/agents/openai.yaml deleted file mode 100644 index 2f76eace4..000000000 --- a/.agents/skills/code-change-verification/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Code Change Verification" - short_description: "Prioritize risks and verify code changes before merge." - default_prompt: "Use $code-change-verification for an ordinary requested diff review with prioritized findings." diff --git a/.agents/skills/issue-triage/SKILL.md b/.agents/skills/issue-triage/SKILL.md index d8512cdfd..15f84e3b1 100644 --- a/.agents/skills/issue-triage/SKILL.md +++ b/.agents/skills/issue-triage/SKILL.md @@ -1,112 +1,13 @@ --- name: issue-triage -description: Assess whether a GitHub issue is fixed, needs implementation, or can be closed by checking related work and current code. Use for issue completion/triage requests. Status questions are read-only; comment, close, or change labels only when the conversation authorizes that action. +description: Verify issue completion against current implementation and merged work. Use for issue triage; comment, close, or change labels only when authorized. --- - # Issue Triage -Use this skill when the user provides a GitHub issue URL and asks "can this be closed?", "is this already implemented?", "check completion status", or similar triage questions. +- Resolve the issue repository separately from the implementation repository: `rustfs/backlog` tracks work in `rustfs/rustfs`. Pass `--repo` explicitly to GitHub queries. +- Read the issue body, relevant comments, linked PRs, checklist, and sub-issues with `gh issue view`. Search explicit links, the full issue URL, qualified references, and subject keywords; an empty search result does not prove implementation is absent. +- Fetch the implementation base and inspect its current code. For each merged candidate, verify `git merge-base --is-ancestor /`; a title, commit message, or merged state alone is insufficient. A local checkout may be stale or on another branch. +- Verify every checklist/sub-issue before declaring completion. For batches, paginate the entire requested issue scope, exclude PR entries, and filter by author only when requested. +- Recommend closing only when all requested behavior is present or evidence shows the issue is superseded. Otherwise name what remains. A status request is read-only; reuse existing authority for comments/closing/labels, and follow [Git and PR rules](../../references/pull-requests.md) before posting. Use Chinese for `rustfs/backlog`, existing repository labels only, and a closing comment naming the verified behavior and PRs. -## Workflow - -### 1. Fetch issue context - -```bash -gh issue view --repo --json title,body,state,comments,labels,updatedAt -``` - -Read the issue body to understand what was requested. Extract: -- The specific feature/fix/behavior described. -- Any linked PRs or commits mentioned in the body or comments. -- Any checklist items or sub-issues. - -Resolve the issue repository and implementation repository separately (for example, `rustfs/backlog` tracks work in `rustfs/rustfs`). Pass the implementation repository explicitly to PR queries; the current checkout may belong to another repository. - -### 2. Search for related work - -Search git history for commits referencing the issue: -```bash -git log --oneline --all --grep="" | head -30 -``` - -Search for related PRs: -```bash -gh pr list --repo --search "" --state all --json number,title,state,mergedAt -``` - -Also search qualified issue references and subject keywords; for same-repository -issues, include `#`. Follow explicit links even without a text match. A search -page with no match does not prove the work is absent. - -If the issue mentions specific PRs, check their status: -```bash -gh pr view --repo --json state,mergedAt,title,mergeCommit,baseRefName -``` - -### 3. Verify implementation - -Fetch the implementation repository's current base branch. For each merged candidate, verify its merge commit is present and inspect the current code for the claimed behavior; a commit message match alone is not proof: -```bash -git fetch -git merge-base --is-ancestor / -``` - -If the issue describes a specific defect, inspect the fetched base's code rather than assuming the current checkout contains it: -```bash -git show /:crates//src/.rs -``` - -For issues with checklists, verify each item individually. If sub-items are tracked as separate issues, check those too: -```bash -gh issue view --repo --json state -``` - -### 4. Determine verdict - -- **All items fixed and merged**: Recommend closing; name the verified PRs and behavior. -- **Some items fixed, some remaining**: Keep open; report each remaining item. -- **Not yet implemented**: Keep open; report what remains. -- **Superseded or no longer relevant**: Recommend closing with evidence. - -### 5. Take action - -For a status-only request, return the assessment without GitHub writes. If commenting, closing, or label edits are authorized, perform only those actions; do not ask again for authority already given. Prepare the final assessment before asking for any missing authority. Write `rustfs/backlog` issue content in Chinese. - -Close with comment: -```bash -gh issue close --repo --comment "" -``` - -Comment without closing: -```bash -gh issue comment --repo --body-file /tmp/triage.md -``` - -Update labels only when label changes are authorized, using existing repository labels; never add tool-specific labels: -```bash -gh issue edit --repo --add-label "" -``` - -Always use `--body-file` for multiline content, never inline `--body`. - -### 6. Handle multi-issue batches - -When the user asks to check multiple issues (e.g., "check all issues by user X" or "scan backlog for closable issues"): -1. List the full requested scope with pagination (for example `gh api --paginate 'repos//issues?state=open&per_page=100'`, excluding entries with `pull_request`). Add an author filter only when the user requested one; the default page/limit is not evidence that all issues were checked. -2. For each issue, run steps 1-5 above. -3. Report a summary table of all triaged issues with verdicts. - -## Report - -Identify the issue and current state, verified implementation/PR evidence, -remaining items, verdict, and action actually taken. Use a table for batches; -a single issue does not require a heading for each field. Follow step 4's -verdicts without repeating the assessment in another template. - -## Notes - -- The user may ask in Chinese ("是否可以关闭", "检查完成情况"); respond in the same language. -- When closing, always include a summary of what was fixed and which PRs resolved it — this creates a useful audit trail. -- For issues in `rustfs/backlog`, use `--repo rustfs/backlog`. -- For issues in `rustfs/rustfs`, use `--repo rustfs/rustfs`. -- If the issue has sub-issues (GitHub sub-issues API), check each one's state before declaring the parent complete. +Report the issue, current state, implementation evidence, remaining work, verdict, and action actually taken. Use a table for batches. Write multiline comments via `--body-file`; when closing, post the prepared comment before closing without an inline multiline body. diff --git a/.agents/skills/pr-review/SKILL.md b/.agents/skills/pr-review/SKILL.md index f1b212f49..7cb99cfc6 100644 --- a/.agents/skills/pr-review/SKILL.md +++ b/.agents/skills/pr-review/SKILL.md @@ -1,93 +1,20 @@ --- name: pr-review -description: Review a GitHub PR from a URL or number using its actual base/head and risk-appropriate code review. Use when the user asks for a PR review, not a status lookup or PR wording edit. Publish a review only when authorized; delegation and monitoring follow the requested scope and root AGENTS.md. +description: Review a GitHub PR using its exact base/head and repository risk policy. Use for requested PR reviews; publish or fix only within conversation authorization. --- - # PR Review -Use this skill for PR context and review delivery. An ordinary review request is read-only unless the conversation also authorizes posting or fixes. Reuse that authorization without asking again; prepare the review before requesting any missing publication approval. +1. Resolve the PR repository and remote; the current checkout may belong elsewhere. Read the PR purpose and linked issues, then fetch the actual base and PR head: -## Prerequisites + ```bash + gh pr view --repo --json title,author,state,body,baseRefName,headRefName,baseRefOid,headRefOid + git fetch refs/pull//head + git diff ... + ``` -- Follow root `AGENTS.md`; classify risk with the [review policy](../../references/adversarial-validation.md) and consult relevant [change-style and boundary rules](../../references/implementation.md). -- Select `code-change-verification` for ordinary review or `adversarial-validation` for explicitly adversarial, substantial, or high-risk review; do not run both on the same diff. - -## Workflow - -### 1. Gather PR context - -```bash -gh pr view --repo --json title,author,state,body,additions,deletions,changedFiles,commits,baseRefName,headRefName,baseRefOid,headRefOid -gh pr diff --repo --name-only -``` - -Read the PR body and linked issues to understand the change's purpose. If the PR references an issue, fetch that too: -```bash -gh issue view --repo --json title,body,state -``` - -### 2. Fetch the diff and classify the change - -```bash -git fetch refs/pull//head -git diff ... --stat -``` - -Resolve `` to the PR repository; do not assume the current checkout's `origin` or `main` matches. Record the exact base/head used. If either moved during fetching, refresh the snapshot before reviewing. Classify using the repository review policy; instruction changes that affect agent execution are mechanical, not exempt. - -### 3. Review the changed behavior - -Group files by functional area to trace callers and invariants. Use the root risk tier's review shape and only matching lenses. File count does not authorize delegation. When delegation is explicitly authorized, high-risk/substantial reviews use exactly two independent reviewers with the applicable lenses split between them; otherwise use two fresh sequential passes. Reviewers do not spawn further agents. - -Findings need a concrete failure scenario with `file:line`; a null verdict briefly names the relevant probes. Reuse existing evidence and choose local checks from the final diff under the root verification policy. - -### 4. Check CI status - -```bash -gh pr checks --repo -``` - -Investigate a failed check when it bears on a finding or the user requested CI diagnosis/merge readiness: -```bash -gh run view --repo --log-failed --job= -``` - -Use current evidence to distinguish pre-existing, flaky, and PR-caused failures. Do not classify them by guesswork or turn a code-only review into unrelated CI repair. - -### 5. Synthesize findings - -Report the PR, reviewed base/head, and risk tier, then summarize the assessment. -Use the selected review's P0–P3 ratings and root finding standard: supported -findings with `file:line`, failure scenario, and fix, or `No findings`. -State the observed check status, including pending or unavailable checks, and -the verdict (`APPROVE`, `REQUEST_CHANGES`, or `COMMENT`). Do not infer a pass -from missing checks or add style nits to populate a clean review. - -### 6. Post the review - -Only when posting is authorized, write the review body to a temp file and post via CLI. Refresh the PR head first; if it changed, review the delta and update the verdict before posting: -```bash -# Request changes -gh pr review --repo --request-changes --body-file /tmp/pr_review.md - -# Approve -gh pr review --repo --approve --body-file /tmp/pr_review.md - -# Comment only (no verdict) -gh pr review --repo --comment --body-file /tmp/pr_review.md -``` - -For authorized inline comments, use [the submission example](references/posting.md). - -Always use `--body-file` or `--input`, never inline multiline `--body`. - -### 7. Handle follow-up - -Follow the [PR lifecycle](../../references/pull-requests.md) and any explicit monitoring request. For follow-up, fetch the new head and compare the recorded reviewed SHA with the new SHA; revisit affected callers and findings. Never use an unfetched `origin/pull//head` ref as evidence. Update the posted review or resolve addressed threads only within existing authorization. - -## Notes - -- The user may ask for review in Chinese; respond in the same language but keep the review body in English per AGENTS.md rules. -- When the user asks for "多角色对抗 review", run the full adversarial validation protocol — this skill's step 3 covers that. -- If the PR is from a fork, check `maintainerCanModify` before attempting to push fixes. -- For very large PRs, batch the review by functional area while keeping the same bounded review shape. + Record both SHAs; refresh if either moved during fetching. Follow relevant [implementation boundaries](../../references/implementation.md). +2. Apply the [risk policy](../../references/adversarial-validation.md). Ordinary reviews use the root finding standard directly. For explicit adversarial, substantial, or high-risk reviews, use [the domain probes](../adversarial-validation/SKILL.md). File count does not authorize delegation; use exactly two independent reviewers only when authorized, otherwise two fresh sequential passes for that risk tier. Reviewers do not spawn further agents. +3. Check `gh pr checks --repo `. Investigate failures when relevant to a finding or a requested CI/readiness diagnosis. Distinguish pending, unavailable, pre-existing, flaky, and PR-caused states using evidence; a code review does not authorize unrelated repairs. +4. Report the reviewed SHAs, risk tier, supported findings or `No findings`, material verification limits, check state, and verdict. P0/P1 findings block approval. Severity: P0 = demonstrated data loss, security breach, remote crash, or deadlock; P1 = correctness, compatibility, or material hot-path regression; P2 = a concrete maintainability defect; P3 = optional style, only when requested. +5. When posting is authorized, follow [Git and PR rules](../../references/pull-requests.md), recheck the remote head, and review any delta before submitting. Use `gh pr review` with `--approve`, `--request-changes`, or `--comment` and `--body-file`; use [the API example](references/posting.md) for authorized inline comments. Reuse existing authorization. +6. Follow the repository PR lifecycle and explicit monitoring scope. Fetch new heads before comparing to the reviewed SHA; never rely on an unfetched `origin/pull//head`. Push fixes or resolve threads only when authorized; check `maintainerCanModify` before a fork push. diff --git a/.agents/skills/rust-code-quality/SKILL.md b/.agents/skills/rust-code-quality/SKILL.md deleted file mode 100644 index e63afb78d..000000000 --- a/.agents/skills/rust-code-quality/SKILL.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -name: rust-code-quality -description: Run a focused Rust quality review when the user requests one or a selected review workflow needs Rust-specific checks for changed behavior. Do not auto-load for every implementation edit, comment-only or formatting-only Rust diff, or repeat an already completed review. ---- - -# Rust Code Quality Gate - -Use this skill for a dedicated Rust review to cover rules that `cargo clippy` -does not catch. - -Search matches and checklist items are candidates, not findings. Apply the root -finding standard; distinguish a demonstrated bug, an explicit rule violation, -and an optional preference. P2/P3 suggestions do not need to be invented or -included in an otherwise clean correctness review. - -## Quick Start - -1. Identify changed `.rs` files. -2. Run the matching candidate searches on changed files. -3. Apply the manual checklist sections whose behavior the diff touches. -4. Report or rebut every finding with evidence; P0/P1 findings block approval. - Fix them when implementation is authorized; a read-only review reports them. - -## Automated Checks - -Use these searches to find candidates in changed `.rs` files. Inspect syntax, -`#[cfg(test)]` scope, and the changed hunk before reporting a finding; text -filters do not reliably distinguish production code from tests. - -```bash -# 1. unwrap/expect candidates -rg -n '\.unwrap\(\)|\.expect\(' - -# 2. Silent type truncation via `as` cast -rg -n ' as (u8|u16|u32|u64|usize|i8|i16|i32|i64|isize)\b' - -# 3. String as error type -rg -n 'Result<.*String>' - -# 4. Box in public APIs -rg -n 'Box - -# 5. println/eprintln in production -rg -n 'println!|eprintln!' - -# 6. Ordering::Relaxed usage (verify each is intentional) -rg -n 'Ordering::Relaxed' - -# 7. Default substituted for a possibly-required value (judge each: is the value optional by domain?) -rg -n 'unwrap_or_default\(\)|unwrap_or\(' -``` - -## Manual Review Checklist - -For the Rust diff under review, verify: - -### Error Handling -- [ ] Every production `unwrap()` or `expect()` is infallible by type or a checked invariant; explain only non-obvious invariants, using an existing type, a useful `expect` message, or a concise comment -- [ ] No `Result<_, String>` in public API signatures -- [ ] Public library APIs use domain errors unless deliberate error erasure at a boundary is part of the contract -- [ ] `Error::source()` is overridden when inner error is stored -- [ ] Error messages are actionable without exposing secret input - -### Type Safety -- [ ] No silent `as` truncation (negative→unsigned, large→small) -- [ ] Fallible numeric conversions use `TryFrom`/`try_into()` and return a typed error; clamp or saturate only when the domain explicitly requires it -- [ ] Floating-point to integer conversion validates finiteness, sign, and range before conversion - -### Concurrency -- [ ] Lock acquisition order is documented when multiple locks are used, and matches every other call site taking any overlapping subset (ABBA check) -- [ ] No `tokio::sync` lock guard (read or write) held across `.await` without bounded hold time — long-lived read guards wedge writers (#4195) -- [ ] Atomic read-modify-write uses the direct `fetch_*` operation when possible; use `compare_exchange` only for conditional updates -- [ ] `std::sync::Mutex` in async context is held only briefly, never across `.await` - -### Memory and Performance -- [ ] On an identified hot path, report cloning or allocation only with a concrete per-request/per-object cost or benchmark signal -- [ ] Prefer borrowing, moving, `Bytes`/`Arc`, or capacity reservation only when it reduces that cost without obscuring ownership or APIs - -### Recursion Safety -- [ ] Recursion over untrusted, persisted, or otherwise unbounded input has a depth limit or uses iterative traversal -- [ ] Tree/cache traversals handle corrupted/cyclic input safely - -### Testing -- [ ] Tests have an observable failure criterion; delegated assertions, `#[should_panic]`, snapshot/property checks, and meaningful `Result` failures do not need a redundant `assert!` -- [ ] Use `expect` only when its message improves failure diagnosis; do not add boilerplate to self-evident test setup -- [ ] Test volume and line count are never treated as production-code growth - -### Serde -- [ ] Structs from untrusted input reject unknown fields where the compatibility contract permits; otherwise validate security-critical fields explicitly and test the supported input shape -- [ ] `#[serde(default)]` not used on security-critical fields without validation - -### Code Hygiene -- [ ] No `#![allow(dead_code)]` at crate root -- [ ] No camelCase statics or Hungarian notation -- [ ] New string literals don't duplicate existing constants - -### Reuse and Necessity -- [ ] No new helper duplicates `crates/utils`, `crates/common`, the touched crate, the likely domain-owning crate, a relevant direct dependency, or plain std/tokio behavior; reused helpers match the call site's semantics -- [ ] No branch without a nameable concrete trigger; no re-validation of what a validated upstream layer on the same path already guarantees (Cross-Cutting Domain Invariant patterns and pre-destructive-action re-checks are load-bearing — keep them) -- [ ] Error context attached once where actionable, not re-wrapped at every hop; no typed→generic error conversion below aggregation/quorum layers -- [ ] Comments avoid narration and change history while completely stating non-obvious lock, `SAFETY`, durability, compatibility, and unwrap invariants -- [ ] No near-duplicate test pinning the same code path and poison-value class as an existing test (boundary companions — n==max vs max+1, absent/empty/nil UUID — are never near-duplicates) - -## Severity Classification - -- **P0 (Block merge)**: demonstrated data loss, security breach, remote crash, or deadlock -- **P1 (Must fix)**: concrete correctness, compatibility, or material hot-path regression -- **P2 (Should fix)**: avoidable duplication or maintainability issue with a concrete simpler replacement -- **P3 (Nice to fix)**: local style or clarity issue with no behavioral risk - -## Output Template - -Use the calling review's output format. For a standalone review, report supported -findings with severity, location, impact, fix, and validation, or `No findings`. -Include only material unverified checks. Candidate counts are not a quality -metric and do not need a separate scan report. diff --git a/.agents/skills/rustfs-logging-governance/SKILL.md b/.agents/skills/rustfs-logging-governance/SKILL.md deleted file mode 100644 index b00e57216..000000000 --- a/.agents/skills/rustfs-logging-governance/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: rustfs-logging-governance -description: Add or review RustFS `tracing` events with the repository field shape, level policy, privacy boundaries, and guardrails. Use when a change adds or edits a tracing macro/instrumentation site or the logging guardrail script. ---- - -# RustFS Logging Governance - -Apply this skill only to changed logging sites; do not turn a local log edit into -a broad logging cleanup. - -## Workflow - -1. Read the changed function/module context and classify the site as lifecycle, - request/hot path, fallback, external fetch, or summary. -2. Match neighboring structured events and reuse existing `EVENT_*`, - `LOG_COMPONENT_*`, and `LOG_SUBSYSTEM_*` constants. -3. Put stable fields first (`event`, `component`, `subsystem`, `state`/`result`, - then context) and a short label last. -4. Select the level by operational meaning: - - `error`: behavior/security-affecting failure; - - `warn`: degraded/fallback/operator-actionable state; - - `info`: low-frequency lifecycle/mode change; - - `debug`: targeted diagnostics; - - `trace`: repetitive request/object/shard success paths. -5. Never log secrets, tokens, auth headers, credential payloads, raw - attacker-controlled bodies, or merged config dumps. Error strings and - `Debug` output are log surfaces too. -6. Prefer one aggregate summary over inventories or startup banners. -7. Run `./scripts/check_logging_guardrails.sh` and the checks selected by root - `AGENTS.md`. - -Read [logging-governance.md](references/logging-governance.md) only for a broad -logging audit, event-model migration, or guardrail expansion. Ordinary single- -site edits do not require the full workspace scope map. diff --git a/.agents/skills/rustfs-logging-governance/agents/openai.yaml b/.agents/skills/rustfs-logging-governance/agents/openai.yaml deleted file mode 100644 index fce6821a0..000000000 --- a/.agents/skills/rustfs-logging-governance/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "RustFS Logging Governance" - short_description: "Standardize RustFS logs with structured events and guardrails." - default_prompt: "Use $rustfs-logging-governance to standardize or review RustFS logging, reduce noise, and update guardrails." diff --git a/.agents/skills/rustfs-release-publish/SKILL.md b/.agents/skills/rustfs-release-publish/SKILL.md index 5579a3ac1..f15c72471 100644 --- a/.agents/skills/rustfs-release-publish/SKILL.md +++ b/.agents/skills/rustfs-release-publish/SKILL.md @@ -1,172 +1,42 @@ --- name: rustfs-release-publish -description: "Run the RustFS console gate, source version bump, release-branch CI, preview validation, human confirmation, final-tag publication, and post-release milestone, installation, and website updates. Use only when the user explicitly asks to release or publish a RustFS version (发版/发布)." +description: Publish a RustFS version through Console, release-branch CI, preview acceptance, human confirmation, and final publication. Use only for an explicit release request. --- -# RustFS Release Publish (preview-validated pipeline) +# RustFS Release -This skill orchestrates a full release. It wraps `rustfs-release-version-bump` (invoked here with the authorized commit/push/PR scope) with a mandatory preview-tag validation loop before the final tag is published. +Require the exact final SemVer target before version edits or publication. If unspecified, inspect current releases/tags and ask with concrete candidates; do not guess the channel or bump. A named bump type resolves to an exact version that still needs confirmation. Report the confirmed target verbatim; resolve any later mismatch before proceeding. Independent read-only preflight may continue. -The binary reports its build tag (`build::TAG` via shadow_rs; `SHORT_VERSION` in -`rustfs/src/config/cli.rs`), and `build.yml` derives asset names and preview -classification from that tag. Cargo.toml supplies only the no-tag fallback. -Preview and final tags must therefore share the validated source commit; -their tag-dependent version and asset names differ. The channel and cleanup -constraints are defined once under Preview tag naming and Hard rules below. +## Invariants -Pipeline shape: +- Cargo stores ``, never `-preview.N`. Before publication, installation defaults retain the previous available deliverable. Final and preview binaries embed their own tag names, so version/asset names differ despite identical source. +- Use annotated tags without `v`. Preview names are exactly `-preview.`; choose the next unused iteration after fetching tags. Preview Releases are prereleases, never Latest; publish only versioned assets/exact Docker tags, never latest assets, R2, Helm, moving Docker channels, or installation/banner updates. +- `release/` owns the candidate. Retain its history, backport only reviewed fixes, and never merge main wholesale or force-push it. Pin `PREVIEW_HASH` to its exact commit with complete passing CI. Preview and final tags both point there; never tag a later main/branch HEAD or insert another bump. +- Phase failures block dependents. Keep preview Releases until final publication and notes generation finish; CI removes Releases while retaining tags. Never move an existing preview or final tag. -``` -check console main against its latest Release - -> if ahead: publish console -> wait for Release asset + latest API - -> bump Cargo.toml and Cargo.lock to -> merge - -> cut release/ from a selected main commit containing the bump - -> CI green for that exact release-branch commit - -> tag at that commit - -> verify preview Release assets -> run binary locally + console checks - -> validate with latest rc client - -> report preview acceptance results -> STOP for explicit human confirmation - -> tag at the SAME commit (zero delta) -> re-verify CI/release - -> CI deletes the -preview.N Releases (tags kept) - -> verify published images -> publish Helm chart from the validated source - -> close the released version's milestone -> ensure the next version's milestone exists - -> update installation references on main -> update rustfs.com announcement -``` +## Read by Phase -On candidate or preview validation failure: fix lands on main via normal PR, then backport only the needed fix to `release/` through a reviewed PR. Re-run release-branch CI at the new commit and, if a preview was already tagged, tag `` there and restart acceptance. Installation references remain on the previous published deliverable throughout preview validation. +Read only the current phase's procedure; retain completed evidence across turns. Follow root verification, Git/PR, and authorization rules. -## Required inputs +| Phase | Procedure | +|---|---| +| 0 | Clean tree, fetch main/tags, verify GitHub access, then complete the mandatory [Console release gate](references/console-gate.md). A green Console build alone is insufficient. | +| 1–2 | [Prepare/reuse the release candidate and run exact-SHA branch CI](references/release-candidate.md). Source version changes use `rustfs-release-version-bump` with authorized delivery scope. | +| 3 | [Verify the preview build, assets, channels, and notes](references/preview-release.md). | +| 4–5 | [Run the downloaded binary, Console CRUD, and latest-rc matrix](references/preview-acceptance.md). Every check must pass. | +| Confirmation | Complete the gate below and end the turn. | +| 6 | After fresh confirmation, [publish and verify the final tag](references/final-release.md) at `PREVIEW_HASH`. | +| 7 | [Maintain milestones, installation references, and the website](references/post-release-updates.md) only after complete publication. | -- Final target version, for example `1.0.0-beta.10`. -- Preview iteration `N` (default: next unused preview tag for that target; check with `git tag -l '-preview.*'` after `git fetch --tags`). +## Human Confirmation -If the target version is missing or ambiguous, collect the current release/tag baseline and ask before version edits or publication. Continue independent read-only preflight while the answer is pending (see the semver gate below). +After Phases 3–5 pass, recheck that the release branch still equals `PREVIEW_HASH`. Report the target, branch, preview tag/hash, branch CI run, preview Release URL, Console result, and rc matrix. Explicitly ask whether to publish the final tag and end the turn without creating/pushing it. -## Semver gate — resolve the target before version edits or publication +Only a new affirmative user reply to that exact report authorizes Phase 6. The original release request, earlier confirmation, silence, or automated follow-up does not count. Confirmation binds the target, preview tag, and hash; a changed value or repeated/failed acceptance cycle invalidates it. Revalidate and obtain fresh confirmation before continuing. -Versions follow [SemVer 2.0.0](https://semver.org/). Precedence reminder: +## Recovery -``` -1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0 < 1.0.1 < 1.1.0 < 2.0.0 -``` +- Before the final tag exists, land fixes on main, backport to the candidate, verify target versions, and restart branch CI/acceptance. Use a new preview iteration once a preview was tagged; main may advance independently. +- Once the final tag exists, retry publication jobs for that exact tag. A source fix requires a newly confirmed target, not retagging or a newer preview. Phase 7 retries recheck artifact availability and superseding releases. +- If abandoned after the bump merged, report the unpublished version on main and record whether to revert or let the next release overwrite it. Deleting candidate branches or preview tags requires an explicit decision. -Numeric prerelease identifiers compare numerically (`beta.9 < beta.10`), not lexically — see [semver.org spec item 11](https://semver.org/#spec-item-11). Preview tags are internal validation tags layered on top of the target's prerelease channel — they are never themselves a deliverable version and never appear in version files. - -Rules: - -- A request like "发个版" / "release the next version" without an exact version string is ALWAYS ambiguous. Derive the current latest tag (`git tag --sort=-v:refname | head`), then ask the user to choose with concrete candidates, e.g. from `1.0.0-beta.10`: next prerelease `1.0.0-beta.11`, promote to `1.0.0-rc.1`, promote to stable `1.0.0`. Never guess between these — they have very different meanings (channel promotion vs. iteration) and different CI classification consequences. -- After a stable `X.Y.Z` exists, the next version must state which component bumps: patch `X.Y.(Z+1)` for fixes only, minor `X.(Y+1).0` for backward-compatible features, major `(X+1).0.0` for breaking changes. If the user names a bump type but not a number, compute it from the latest stable tag and echo the exact resulting version back for confirmation. -- Echo the final confirmed version string verbatim in your first status report; every later phase must use exactly that string. If at any point the user's wording and the confirmed version diverge, stop and re-confirm. - -## Preview tag naming - -- Use `-preview.N` for every target, e.g. `1.0.0-beta.10-preview.3` or `1.1.0-preview.1`. -- The canonical suffix is exactly `-preview.`. `build.yml` recognizes it before alpha/beta/rc classification and routes it to the preview-only path; any other tag containing `-preview` fails closed instead of being treated as a release. -- A preview Release MUST be published with `isPrerelease=true` and `isLatest=false`. Any `*-latest` preview asset or preview-triggered `latest.json`, R2, Helm, or moving Docker channel tag is a pipeline failure. Docker images may use the exact preview version tag, including its existing variant suffixes. -- Preview Releases are cleaned up by the `cleanup-preview-releases` job after `publish-release` succeeds for the deliverable tag. It deletes every Release whose tag is exactly `-preview.` and never passes `--cleanup-tag`, so the tags survive. - -## Hard rules - -- Before preview, bump only Cargo.toml (workspace package and internal dependency versions) and the corresponding workspace members in Cargo.lock, directly to ``. Keep README installation examples, flake.nix, Chart.yaml, and rustfs.spec on the previous published deliverable until Phase 7. Never write a `-preview.N` suffix into these files; preview identifiers belong to validation tags and artifacts. -- Publishing a tag alone does not make an installation target available. Verify the exact image manifest, Release assets, and source archive before advancing references that consume them. Helm packaging derives its versions from the final tag and waits for that image; it does not require an early Chart.yaml bump on main. -- Preview Release assets are versioned and intentionally visible on the Releases page for the duration of validation. Do not label them Latest or use them to update any latest distribution channel. -- Never delete a preview Release by hand before Phase 6 finishes — Phase 4 downloads its assets and the final Release notes are generated while it still exists. Cleanup is CI's job; only step in manually (`gh release delete "" --yes`, never `--cleanup-tag`) if `cleanup-preview-releases` failed. -- Tags have no `v` prefix. Always annotated: `git tag -a -m "Release "`. -- The release branch is the candidate source during multi-day acceptance. Do not merge main wholesale into it, force-push it, or advance it with unrelated changes. The final tag MUST point at exactly `PREVIEW_HASH` — the commit the validated preview tag points at. Never tag current `main` HEAD or an advanced release-branch HEAD, and never create an extra version-bump commit between preview and final. Phase 7 updates installation references on main after publication; neither tag moves to that follow-up commit. -- When a previous deliverable exists, GitHub Release notes for the preview and final tags MUST use it as their shared comparison baseline: the most recently published non-preview Release before the target. Internal `-preview.N` Releases are explicitly excluded from that selection, even when they point at the same commit as the final tag — cleanup runs after the notes are generated, so the preview Release is still present and would otherwise be picked as the baseline. If no previous deliverable exists, omit `previous_tag_name` and record that GitHub's default baseline fallback was used. -- Generated Release notes carry a workflow-management marker so retries can repair them. Before manually curating a generated body, remove that marker; unmarked non-placeholder notes are preserved by later workflow runs. -- Phases run in order; a failure blocks dependent steps. For a candidate or preview/source acceptance failure before the final tag exists, land the fix on main, backport it to the release branch, verify Cargo there still matches the confirmed target, and restart from release-branch CI in Phase 2. Use the next preview iteration if any preview was already tagged. Main may advance to another target without changing this release candidate. -- Once the final tag exists, preserve its commit. Retry failed publication jobs for that exact tag; do not recreate the tag or restart preview on newer main. If a source change is required after final-tag publication, report the failure and obtain a new target version. Phase 7 failures resume only the failed follow-up after rechecking artifact availability and whether a newer release has superseded it. -- Completing preview acceptance does not authorize the final tag. After Phases 3–5 pass, report the acceptance evidence and stop until the user explicitly confirms continuation. The original release request, an earlier confirmation, silence, or an automated follow-up does not satisfy this gate. -- Confirmation is scoped to the reported ``, ``, and `PREVIEW_HASH`. A failed or repeated acceptance cycle, including any new preview iteration, invalidates prior confirmation and requires a new one. -- If the release is abandoned after Phase 1 merged, main's version files claim a version that was never tagged. Either revert the bump PR or leave it to be overwritten by the next release — but tell the user explicitly and record the decision. Do not delete the release branch or preview tags as part of abandonment without an explicit decision. -- User-facing status updates in Chinese; commits, PR titles/bodies, and tag messages in English. No hard-wrapping in commit messages, PR bodies, or documentation prose — one logical line per sentence/paragraph, let soft wrap handle display. - -## Phase 0 — Preflight - -- `git status --short` clean; `git fetch origin main --tags`. -- `gh auth status` works; confirm you can view `gh release list -L 3`. -- Confirm the exact final target version with the user if not explicit. -- Check whether `release/` already exists before creating it; a resumed release reuses the existing branch and its history. For an in-flight release that already has a preview tag but no branch, anchor the new branch to that tag's commit only after verifying its target versions and prior acceptance evidence. - -### Console release gate - -Read and complete [the Console gate](references/console-gate.md) before Phase 1. Verify the latest published Console asset and exact commit; if Console main is ahead, complete its release and asset verification first. A successful build alone does not satisfy this gate. - -## Phase 1 — Source version bump to the final target (once) - -- If `release/` exists, verify its Cargo.toml and workspace members in Cargo.lock read `` and skip the source bump, even if main has advanced. If the branch versions differ, stop and resolve the mismatch without downgrading main. -- If no branch exists but an unfinished preview tag does, verify its commit has `` in both version files and skip the bump; Phase 2 anchors the branch to that commit. Stop if those files disagree. Otherwise, if main already has `` in both files, skip the bump. Installation references intentionally retain the previous published deliverable during preview; if they were advanced to an unavailable target, restore that baseline before choosing the next candidate. -- Only when neither the release branch, an unfinished preview tag, nor current main already has ``: if main is at a later version, select and verify a historical commit containing `` rather than downgrading main; block if none exists. Otherwise invoke the `rustfs-release-version-bump` skill with stage `prepare`, the final `` (NOT a preview version), and full GitHub flow (commit/push/PR). -- If a bump PR was needed, get it merged into main and record its merge commit. For a new release branch when main already has ``, identify the main commit that introduced those versions. Phase 2 chooses a release candidate containing that commit; an existing release branch keeps its own history and a newer main HEAD is not required. - -Do not wait for the moving latest main HEAD to become green. The release-branch CI in Phase 2 validates the chosen commit before a preview tag is created. - -## Phase 2 — Pin and validate the release candidate, then publish the preview tag - -- Use `release/`. On the first attempt, create it from a selected main commit containing the version bump and intended changes; it need not be the latest main HEAD. On a restart, retain the existing branch and backport only reviewed fixes from main. Verify the branch's Cargo versions still equal ``. If adopting an existing preview, run this branch CI before continuing its acceptance; reuse the tag only when it points to the validated SHA. -- The current `ci.yml` runs automatically on main pushes, not release-branch pushes. Dispatch it explicitly with `gh workflow run ci.yml --ref "release/"`. Locate that dispatch run, verify its `head_sha` equals the release branch's remote HEAD, and require the full expected CI job set to pass, including `Quick Checks`, `Test and Lint`, and `End-to-End Tests (full merge gate)`. Treat a missing or skipped required lane as incomplete. A successful PR check or CI run for a different SHA does not qualify. If the branch advances or a run is cancelled, validate the new SHA again. Do not tag a candidate with failing or incomplete CI. -- Prefer protecting `release/*` against force pushes and deletion and requiring reviewed backport PRs. Check live rulesets rather than assuming the main ruleset covers release branches; report a missing release-branch rule as a gap. -- Set `PREVIEW_HASH` to the CI-validated release-branch commit and recheck the remote branch HEAD immediately before tagging. Report the branch, commit, and CI run URL; do not derive `PREVIEW_HASH` from a later `origin/main` fetch. When adopting an existing preview tag at this SHA, skip tag creation and continue Phase 3. - -```bash -git tag -a "" -m "Release " "$PREVIEW_HASH" -git push origin "" -``` - -Pushing the tag triggers `.github/workflows/build.yml` ("Build and Release"); `docker.yml` chains off it via `workflow_run`. - -The preview run builds versioned artifacts and publishes them in a GitHub prerelease. Docker may publish exact preview image tags. Latest-channel, R2, and Helm publication must be skipped; installation references and the website announcement stay unchanged. - -On a restart after a backport, re-run release-branch CI before setting the new `PREVIEW_HASH`. Use the next unused preview iteration when the validated commit differs from an existing preview tag; never move an existing tag. - -## Phase 3 — CI and preview Release verification - -- Find and watch the tag build: `gh run list --workflow build.yml --branch "" --limit 1` then `gh run watch `. Every build matrix target must succeed (linux x86_64/aarch64 × musl/gnu, macos-aarch64, windows-x86_64). -- Confirm the preview tag resolves to the Phase 2 CI-validated `PREVIEW_HASH`. If the release branch advances during acceptance, repeat Phases 2–5 with a new preview tag. -- Confirm the Release publication jobs (`create-release`, `upload-release-assets`, and `publish-release`) succeed while `update-latest-version` is skipped. -- Verify `gh release view "" --json isPrerelease,assets,url`: `isPrerelease` must be `true`, and the Release must contain all 6 versioned platform zips, checksums, SBOM, and provenance with no `-latest` assets. Confirm `gh api repos/{owner}/{repo}/releases/latest --jq .tag_name` does not return ``. -- Record `PREVIOUS_DELIVERABLE`, selected from published Releases by `publishedAt` after excluding the current tag and every `-preview.N` tag. Verify `gh release view "" --json body --jq .body` contains `## What's Changed` and, when `PREVIOUS_DELIVERABLE` exists, `**Full Changelog**: https://github.com/rustfs/rustfs/compare/...`. For a repository with no previous deliverable, verify a Full Changelog link exists and record the GitHub baseline fallback. -- Confirm Helm is skipped. If preview Docker images are published, confirm they use only exact preview tags (and variant suffixes), with no `latest`, `alpha`, `beta`, or `rc` channel updates. Preview validation covers the built RustFS binaries, embedded console, and rc compatibility; it does not authorize advancing any installation default. - -## Phases 4–5 — Local artifact, Console, and rc acceptance - -Read and complete [preview acceptance](references/preview-acceptance.md): verify the downloaded binary's tag/SHA and readiness, exercise Console CRUD with byte-identical download, and pass the full latest-rc command matrix. Any failure blocks final publication. Retain the results for the confirmation gate below. - -### Manual confirmation gate - -After every Phase 3–5 check passes, verify the release branch still points to `PREVIEW_HASH`. Report the target, release branch, preview tag, `PREVIEW_HASH`, release-branch CI run, preview Release URL, console result, and rc matrix, then explicitly ask the user whether to publish the final tag. End the turn without creating or pushing ``. - -Continue to Phase 6 only after a new user reply explicitly confirms the reported target, preview tag, and commit. A clear affirmative reply to that exact report, such as `确认继续`, is sufficient; if the reply is ambiguous or any reported value changed, ask again. - -## Phase 6 — Publish the final tag on the validated commit - -No second source version bump. Before creating the final tag, recheck the remote `release/` HEAD equals `PREVIEW_HASH`. If it moved after confirmation, the approval no longer applies; validate and obtain confirmation for a new preview. The final tag goes on the exact commit the preview validated: - -```bash -git fetch origin --tags -git rev-parse "^{commit}" # must equal PREVIEW_HASH — abort if not -git tag -a "" -m "Release " "$PREVIEW_HASH" -git push origin "" -``` - -- CI rebuilds from the same source; the only changed input is the tag name, so the binary now self-reports ``. -- Verify the final tag's complete publication path: all matrix and release jobs green; `gh release view ""` shows the full versioned and `-latest` asset set plus checksums, SBOM, and provenance; Docker and Helm workflows succeed; `latest.json` points to ``. A stable target must have `isPrerelease=false` and `isLatest=true`. An alpha/beta/rc target must have `isPrerelease=true`; GitHub does not permit prereleases to be Latest, but the project `latest.json` still advances to the final non-preview target. -- Verify the final Release body contains `## What's Changed` and a Full Changelog link. When `PREVIOUS_DELIVERABLE` exists, the link MUST be `https://github.com/rustfs/rustfs/compare/...` and the baseline MUST equal the preview Release baseline; for example, both `1.0.0-beta.12-preview.1` and `1.0.0-beta.12` compare from `1.0.0-beta.11`. -- Verify the preview cleanup: `cleanup-preview-releases` must succeed, `gh release view ""` must then report `release not found` for every preview iteration of this target, and `git rev-parse "^{commit}"` must still resolve to `PREVIEW_HASH` (the tag is kept). If the job failed, delete the leftover Releases manually with `gh release delete "" --yes` and report it. -- Optionally spot-check `./rustfs --version` from a final-tag artifact — it must report ``. - -## Phase 7 — Milestones, installation references, and website announcement - -Only after Phase 6 succeeds, complete [post-release updates](references/post-release-updates.md): close the released version's milestone and ensure the next version's milestone exists, align installation references on main, then update the existing top banner in `rustfs/rustfs.com`. Milestone maintenance is required for every non-preview release and is independent of installation PR merges or website deployment. A failed or incomplete publication leaves milestones unchanged and installation references and the banner on the previous available version. These follow-up commits never change `PREVIEW_HASH` or either release tag. Track milestone, PR, merge, and deployment states separately from artifact publication; an open PR is not a live website update. - -## Output contract - -Always report: - -- Console gate result: previous/latest Console tags, whether merged changes required a release, `CONSOLE_HASH`, and Console run/Release URLs when a release was published. -- Target version, release branch, release-branch CI run and validated SHA, preview tag(s) used, `PREVIEW_HASH` (which both tags point at). -- Manual confirmation gate status (`WAITING_FOR_CONFIRMATION` or `CONFIRMED`) and its exact target, preview tag, and `PREVIEW_HASH`. -- Per-phase result (PASS/FAIL/BLOCKED) with key evidence: preview and final Release URLs, preview `isPrerelease`/`isLatest` state, final latest-channel state, console check results, the rc command matrix, and the preview-Release cleanup result (deleted Releases plus surviving tags). -- Released-version milestone title, URL, and verified closed state; next-version milestone title, URL, state, and whether it already existed or was created. Report missing milestones or failed checks/updates as incomplete follow-up work. -- Post-release installation PR and verification results; website banner target, text, link, PR, and observed deployment state. Report any remaining merge authorization or failed deployment explicitly rather than claiming the banner is live. -- Any deviation from this pipeline and why the user approved it. +Report completed phase results and incomplete work with evidence: Console previous/latest tags, release need, hash and run/Release URLs; target, branch CI/SHA, previews and hash, confirmation state; preview/final assets, latest-channel state, Console/rc results and cleanup; both milestone states, installation PR checks/merge state, and website text/link/PR/deployment state. Keep artifact publication separate from follow-up delivery; do not call an open PR a live update. Report deviations and their authorization. diff --git a/.agents/skills/rustfs-release-publish/references/final-release.md b/.agents/skills/rustfs-release-publish/references/final-release.md new file mode 100644 index 000000000..c637112fd --- /dev/null +++ b/.agents/skills/rustfs-release-publish/references/final-release.md @@ -0,0 +1,22 @@ +# Final Release Publication + +Read only after fresh user confirmation of the preview acceptance report. The [parent confirmation gate](../SKILL.md#human-confirmation) applies. + +## Phase 6 — Publish the final tag on the validated commit + +No second source version bump. Before creating the final tag, recheck the remote `release/` HEAD equals `PREVIEW_HASH`. If it moved after confirmation, the approval no longer applies; validate and obtain confirmation for a new preview. The final tag goes on the exact commit the preview validated: + +```bash +git fetch origin --tags +git rev-parse "^{commit}" # must equal PREVIEW_HASH — abort if not +git tag -a "" -m "Release " "$PREVIEW_HASH" +git push origin "" +``` + +- CI rebuilds from the same source; the only changed input is the tag name, so the binary now self-reports ``. +- Verify the final tag's complete publication path: all matrix and release jobs green; `gh release view ""` shows the full versioned and `-latest` asset set plus checksums, SBOM, and provenance; Docker and Helm workflows succeed; `latest.json` points to ``. A stable target must have `isPrerelease=false` and `isLatest=true`. An alpha/beta/rc target must have `isPrerelease=true`; GitHub does not permit prereleases to be Latest, but the project `latest.json` still advances to the final non-preview target. +- Verify the final Release body contains `## What's Changed` and a Full Changelog link. When `PREVIOUS_DELIVERABLE` exists, the link MUST be `https://github.com/rustfs/rustfs/compare/...` and the baseline MUST equal the preview Release baseline; for example, both `1.0.0-beta.12-preview.1` and `1.0.0-beta.12` compare from `1.0.0-beta.11`. +- Verify the preview cleanup: `cleanup-preview-releases` must succeed, `gh release view ""` must then report `release not found` for every preview iteration of this target, and `git rev-parse "^{commit}"` must still resolve to `PREVIEW_HASH` (the tag is kept). If the job failed, delete the leftover Releases manually with `gh release delete "" --yes` and report it. +- Optionally spot-check `./rustfs --version` from a final-tag artifact — it must report ``. + +Never pass `--cleanup-tag` when removing preview Releases. Remove them manually only if `cleanup-preview-releases` failed, after final publication and notes generation. Record deleted Releases and surviving tags. diff --git a/.agents/skills/rustfs-release-publish/references/preview-release.md b/.agents/skills/rustfs-release-publish/references/preview-release.md new file mode 100644 index 000000000..2774bff7e --- /dev/null +++ b/.agents/skills/rustfs-release-publish/references/preview-release.md @@ -0,0 +1,24 @@ +# Preview Release Verification + +Read for Phase 3 after the candidate passed exact-SHA CI. The [parent release invariants](../SKILL.md) apply. + +## Preview channels + +- Use `-preview.N` for every target, e.g. `1.0.0-beta.10-preview.3` or `1.1.0-preview.1`. +- The canonical suffix is exactly `-preview.`. `build.yml` recognizes it before alpha/beta/rc classification and routes it to the preview-only path; any other tag containing `-preview` fails closed instead of being treated as a release. +- A preview Release MUST be published with `isPrerelease=true` and `isLatest=false`. Any `*-latest` preview asset or preview-triggered `latest.json`, R2, Helm, or moving Docker channel tag is a pipeline failure. Docker images may use the exact preview version tag, including its existing variant suffixes. +- Preview Releases are cleaned up by the `cleanup-preview-releases` job after `publish-release` succeeds for the deliverable tag. It deletes every Release whose tag is exactly `-preview.` and never passes `--cleanup-tag`, so the tags survive. + +## Phase 3 — CI and preview Release verification + +- Find and watch the tag build: `gh run list --workflow build.yml --branch "" --limit 1` then `gh run watch `. Every build matrix target must succeed (linux x86_64/aarch64 × musl/gnu, macos-aarch64, windows-x86_64). +- Confirm the preview tag resolves to the Phase 2 CI-validated `PREVIEW_HASH`. If the release branch advances during acceptance, repeat Phases 2–5 with a new preview tag. +- Confirm the Release publication jobs (`create-release`, `upload-release-assets`, and `publish-release`) succeed while `update-latest-version` is skipped. +- Verify `gh release view "" --json isPrerelease,assets,url`: `isPrerelease` must be `true`, and the Release must contain all 6 versioned platform zips, checksums, SBOM, and provenance with no `-latest` assets. Confirm `gh api repos/{owner}/{repo}/releases/latest --jq .tag_name` does not return ``. +- Record `PREVIOUS_DELIVERABLE`, selected from published Releases by `publishedAt` after excluding the current tag and every `-preview.N` tag. Verify `gh release view "" --json body --jq .body` contains `## What's Changed` and, when `PREVIOUS_DELIVERABLE` exists, `**Full Changelog**: https://github.com/rustfs/rustfs/compare/...`. For a repository with no previous deliverable, verify a Full Changelog link exists and record the GitHub baseline fallback. +- Confirm Helm is skipped. If preview Docker images are published, confirm they use only exact preview tags (and variant suffixes), with no `latest`, `alpha`, `beta`, or `rc` channel updates. Preview validation covers the built RustFS binaries, embedded console, and rc compatibility; it does not authorize advancing any installation default. + +## Release notes + +- When a previous deliverable exists, GitHub Release notes for the preview and final tags MUST use it as their shared comparison baseline: the most recently published non-preview Release before the target. Internal `-preview.N` Releases are explicitly excluded from that selection, even when they point at the same commit as the final tag — cleanup runs after the notes are generated, so the preview Release is still present and would otherwise be picked as the baseline. If no previous deliverable exists, omit `previous_tag_name` and record that GitHub's default baseline fallback was used. +- Generated Release notes carry a workflow-management marker so retries can repair them. Before manually curating a generated body, remove that marker; unmarked non-placeholder notes are preserved by later workflow runs. diff --git a/.agents/skills/rustfs-release-publish/references/release-candidate.md b/.agents/skills/rustfs-release-publish/references/release-candidate.md new file mode 100644 index 000000000..ad771d3e2 --- /dev/null +++ b/.agents/skills/rustfs-release-publish/references/release-candidate.md @@ -0,0 +1,37 @@ +# Release Candidate Preparation + +Read for Phases 1–2. The [parent release invariants](../SKILL.md) and Console gate apply. + +## Candidate Resume Preflight + +- `git status --short` clean; `git fetch origin main --tags`. +- `gh auth status` works; confirm you can view `gh release list -L 3`. +- Confirm the exact final target version with the user if not explicit. +- Check whether `release/` already exists before creating it; a resumed release reuses the existing branch and its history. For an in-flight release that already has a preview tag but no branch, anchor the new branch to that tag's commit only after verifying its target versions and prior acceptance evidence. + +## Phase 1 — Source version bump to the final target (once) + +- If `release/` exists, verify its Cargo.toml and workspace members in Cargo.lock read `` and skip the source bump, even if main has advanced. If the branch versions differ, stop and resolve the mismatch without downgrading main. +- If no branch exists but an unfinished preview tag does, verify its commit has `` in both version files and skip the bump; Phase 2 anchors the branch to that commit. Stop if those files disagree. Otherwise, if main already has `` in both files, skip the bump. Installation references intentionally retain the previous published deliverable during preview; if they were advanced to an unavailable target, restore that baseline before choosing the next candidate. +- Only when neither the release branch, an unfinished preview tag, nor current main already has ``: if main is at a later version, select and verify a historical commit containing `` rather than downgrading main; block if none exists. Otherwise invoke the `rustfs-release-version-bump` skill with stage `prepare`, the final `` (NOT a preview version), and full GitHub flow (commit/push/PR). +- If a bump PR was needed, get it merged into main and record its merge commit. For a new release branch when main already has ``, identify the main commit that introduced those versions. Phase 2 chooses a release candidate containing that commit; an existing release branch keeps its own history and a newer main HEAD is not required. + +Do not wait for the moving latest main HEAD to become green. The release-branch CI in Phase 2 validates the chosen commit before a preview tag is created. + +## Phase 2 — Pin and validate the release candidate, then publish the preview tag + +- Use `release/`. On the first attempt, create it from a selected main commit containing the version bump and intended changes; it need not be the latest main HEAD. On a restart, retain the existing branch and backport only reviewed fixes from main. Verify the branch's Cargo versions still equal ``. If adopting an existing preview, run this branch CI before continuing its acceptance; reuse the tag only when it points to the validated SHA. +- The current `ci.yml` runs automatically on main pushes, not release-branch pushes. Dispatch it explicitly with `gh workflow run ci.yml --ref "release/"`. Locate that dispatch run, verify its `head_sha` equals the release branch's remote HEAD, and require the full expected CI job set to pass, including `Quick Checks`, `Test and Lint`, and `End-to-End Tests (full merge gate)`. Treat a missing or skipped required lane as incomplete. A successful PR check or CI run for a different SHA does not qualify. If the branch advances or a run is cancelled, validate the new SHA again. Do not tag a candidate with failing or incomplete CI. +- Prefer protecting `release/*` against force pushes and deletion and requiring reviewed backport PRs. Check live rulesets rather than assuming the main ruleset covers release branches; report a missing release-branch rule as a gap. +- Set `PREVIEW_HASH` to the CI-validated release-branch commit and recheck the remote branch HEAD immediately before tagging. Report the branch, commit, and CI run URL; do not derive `PREVIEW_HASH` from a later `origin/main` fetch. When adopting an existing preview tag at this SHA, skip tag creation and continue Phase 3. + +```bash +git tag -a "" -m "Release " "$PREVIEW_HASH" +git push origin "" +``` + +Pushing the tag triggers `.github/workflows/build.yml` ("Build and Release"); `docker.yml` chains off it via `workflow_run`. + +The preview run builds versioned artifacts and publishes them in a GitHub prerelease. Docker may publish exact preview image tags. Latest-channel, R2, and Helm publication must be skipped; installation references and the website announcement stay unchanged. + +On a restart after a backport, re-run release-branch CI before setting the new `PREVIEW_HASH`. Use the next unused preview iteration when the validated commit differs from an existing preview tag; never move an existing tag. diff --git a/.agents/skills/rustfs-release-version-bump/SKILL.md b/.agents/skills/rustfs-release-version-bump/SKILL.md index 104a6b647..482ce9ac0 100644 --- a/.agents/skills/rustfs-release-version-bump/SKILL.md +++ b/.agents/skills/rustfs-release-version-bump/SKILL.md @@ -1,118 +1,24 @@ --- name: rustfs-release-version-bump -description: "Prepare Cargo versions for an exact RustFS target, or align installation references after its artifacts are published, with verification and optional commit/push/PR delivery. Use for an explicit version bump or when invoked by the release-publish workflow." +description: Prepare an exact RustFS Cargo version or align installation references after publication. Use for requested version bumps or the release workflow. --- -# RustFS Release Version Bump +# Release Version Files -Use this skill to prepare and verify release version files. Commit, push, and PR steps apply only when included in the user's delivery scope; publishing release tags belongs to `rustfs-release-publish`. +Require an exact target; ask if missing or ambiguous. Reject targets containing `-preview`: those are tag-only. Infer `post-release` only from an explicit request or parent workflow; otherwise use `prepare`. Delivery defaults to local edit/verify; commit, push, PR, and merge follow existing authorization and [Git rules](../../references/pull-requests.md). -## Required inputs +| Stage | Files and constraints | +|---|---| +| `prepare` | Only `Cargo.toml` and `Cargo.lock`: workspace package, internal dependency, and workspace member versions become ``. External dependencies stay unchanged. | +| `post-release` | Only `README.md`, `README_ZH.md`, `flake.nix`, `helm/rustfs/Chart.yaml`, and `rustfs.spec`. Cargo may already target the next release; leave it untouched. | -- Exact target version, for example `1.0.0-beta.4`. -- Stage: `prepare` (default) or `post-release`. Infer `post-release` only when the user or parent release workflow explicitly requests installation updates after publication; a normal version bump means `prepare`. -- Delivery scope: local (`edit/verify`), git (`commit/push`), or GitHub - (`commit/push/PR`). Derive it from the conversation; when unspecified, prepare - and verify locally without blocking on a delivery question. +Before installation edits, verify the exact non-preview Release, downloadable assets/source archive, pullable `rustfs/rustfs:` image manifest, and published Helm chart. Block on missing artifacts. Do not downgrade defaults if a newer deliverable superseded the target. Preview preparation retains the previous published installation references; follow-up commits never replace either validated tag. -If target version is missing or ambiguous, stop and ask before editing. +Packaging policy: -Reject any target version containing `-preview`: preview identifiers are tag-only (see `rustfs-release-publish`) and must never be written into version files. If asked for one, stop and point to the release pipeline instead of editing. +- Docker image tags have no `v` prefix. Derive chart/app versions with `scripts/helm_chart_version.sh ` (`beta.N -> 0.N.0`; other versions unchanged). Helm CI derives versions from the final tag, so no early chart bump is required. +- RPM `Version` is numeric; `Release` is the prerelease suffix or `1` for stable. Expanded `Source0` and the unpack directory must resolve to the exact target including its suffix. Add the changelog entry using current git identity, date, and target; never copy an example identity/date. +- Changing these mappings requires explicit confirmation. -## Read before editing +Verification follows root tiers: `prepare` validates Cargo metadata with the updated lockfile and checks every workspace/internal version with no unrelated lockfile updates. `post-release` renders Helm with the verified image, runs `scripts/test_helm_chart_version.sh` for chart version edits, and checks README, Nix, and RPM references. Run `git diff --check`; report unresolved required checks as `BLOCKED` without unrelated fixes. -- `AGENTS.md` (root and nearest path-specific files). -- `.github/pull_request_template.md` only when preparing a PR. -- Current branch status and diff against `origin/main`. - -## Stage boundaries - -`prepare` updates only: - -- `Cargo.toml` -- `Cargo.lock` - -`post-release` updates installation and packaging references only: - -- `README.md` -- `README_ZH.md` -- `flake.nix` -- `helm/rustfs/Chart.yaml` -- `rustfs.spec` - -During preview, installation references intentionally retain the previous published deliverable. Do not sweep them into a source bump to make every version string match. `flake.nix` builds local source, but its package label is aligned with the other packaging references after publication. - -Before `post-release` edits, verify that the exact non-preview target has a published GitHub Release, downloadable assets and source archive, and a pullable `rustfs/rustfs:` image manifest. If any prerequisite is missing, report `BLOCKED` and leave installation references unchanged. If a newer deliverable has already superseded this target, do not downgrade installation defaults during a retry. - -Helm CI derives chart versions from the triggering tag, so the final tag can retain the previous Chart.yaml values. Update the repository copy only after the target image and published chart are available. Neither post-release changes nor their merge commit may replace the preview-validated final tag. - -## Hard release policy - -- Docker doc tags use `` (for example `rustfs/rustfs:1.0.0-beta.4`), not `v`. -- Derive Helm chart and app versions with `scripts/helm_chart_version.sh `; the existing mapping is `beta.N -> 0.N.0`, with other target versions retained. -- `rustfs.spec` `Release` uses the prerelease suffix (for example `beta.4`), or `1` for a stable release. -- Do not change these rules without explicit confirmation. - -## Step-by-step workflow - -1. Confirm intent and isolate scope -- Use the exact target and delivery scope already supplied; ask only for a missing or ambiguous target or a material release-policy choice. -- Inspect current branch and ensure only release-related files are touched for this task. - -2. Update workspace versions (`prepare` only) -- Bump `[workspace.package].version` in `Cargo.toml`. -- Bump internal workspace crate dependency versions in `Cargo.toml`. -- Update `Cargo.lock` so workspace package versions match target version. -- Re-scan Cargo.toml and workspace members in Cargo.lock for partial leftovers; leave external dependency versions unchanged. - -3. Update installation references (`post-release` only) -- `README.md` and `README_ZH.md`: update versioned Docker examples to target version. -- `flake.nix`: update package version to target version. -- `helm/rustfs/Chart.yaml`: use the app and chart versions returned by `scripts/helm_chart_version.sh `. -- `rustfs.spec`: -- Set `Version` to the numeric version and `Release` to the prerelease suffix (example `beta.4`), or `1` for a stable release. Verify that `Source0` and the unpacked source directory resolve to the exact published target, including its prerelease suffix when present. -- Add/update top changelog entry with exact format: -- `* Thu May 20 2026 houseme ` -- `- Update RPM package to RustFS 1.0.0-beta.4` -- Changelog identity and time must come from current environment: -- `git config --get user.name` -- `git config --get user.email` -- `date '+%a %b %d %Y'` -- Changelog version text must match target release version exactly. - -4. Verify before shipping -- Follow the root verification tiers for the final diff instead of running a full-workspace gate for version strings. -- For `prepare`, validate Cargo metadata with the updated lockfile and confirm workspace package/internal dependency versions agree. Do not accept a lockfile containing unrelated dependency updates. -- For `post-release`, render the Helm chart and confirm its default image is the verified target; run `scripts/test_helm_chart_version.sh` when chart versions change. Check the README image tags, Nix package version, and expanded RPM source URL against that same target. -- Run `git diff --check` for either stage. Report unresolved required checks as `BLOCKED`; do not silently widen scope to fix unrelated issues. - -5. Commit strategy (only when committing is authorized) -- Use `chore(release): prepare ` for `prepare` and `chore(release): align installation references for ` for `post-release`. -- These stages happen on opposite sides of publication; do not combine them in a preview-preparation commit or PR. -- Stage only intended release files; do not include unrelated working tree changes. - -6. Push and PR (only for the authorized delivery scope) -- Push branch: -- Use the user-requested or configured push remote: `git push -u ` (first push), or `git push` when tracking is already configured. -- Create PR with template headings unchanged: -- `gh pr create --base main --head --title ... --body-file ...` -- PR title/body must be English. -- Use `N/A` for non-applicable template sections. -- Include verification commands and any `BLOCKED` reason clearly. - -## Recommended check commands - -- `git status --short --branch` -- `git diff --name-only origin/main...HEAD` -- `git diff --stat origin/main...HEAD` -- `rg -n "|" Cargo.toml Cargo.lock README.md README_ZH.md flake.nix helm/rustfs/Chart.yaml rustfs.spec` - -## Output contract - -When using this skill, always report: - -- Target version and stage. -- Files changed. -- Any assumptions or uncertainties requiring confirmation. -- Verification result (`PASSED` or `BLOCKED`) with key evidence. -- Commit message(s) used. -- Push status and PR URL when GitHub flow is requested. +For authorized commits, keep stages separate: `chore(release): prepare ` or `chore(release): align installation references for `. Report target/stage, changed files, verification, material uncertainty, and actual commit/push/PR state. diff --git a/.agents/skills/test-coverage-improver/SKILL.md b/.agents/skills/test-coverage-improver/SKILL.md deleted file mode 100644 index 2ee91cb18..000000000 --- a/.agents/skills/test-coverage-improver/SKILL.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -name: test-coverage-improver -description: Analyze a supplied coverage report or perform an explicitly requested RustFS coverage assessment, rank uncovered risks, and propose focused tests. Do not trigger for ordinary implementation verification, a single regression test, documentation wording, or release preparation without a coverage request. ---- - -# Test Coverage Improver - -Use this skill when you need a prioritized, risk-aware plan to improve tests from coverage results. - -## Usage assumptions -- Focus scope is either changed lines/files, a module, or the whole repository. -- Reuse a supplied coverage artifact when its revision, scope, and format match. -- If required context is missing, call out assumptions explicitly before proposing work. - -## Workflow - -1. Define scope and baseline - - Derive the revision and scope from the request, diff, or supplied report. - - Default to the affected files/module; whole-workspace coverage requires that - scope in the request. Ask only if a wrong scope would change the result. - -2. Obtain coverage evidence - - First inspect a matching existing artifact; do not regenerate it merely - because this skill was selected. - - If measurement is needed, read the Coverage section of - [the testing guide](../../../docs/testing/README.md#coverage), check disk - space/tool availability, and select package/test-scoped `cargo llvm-cov` - using the repository's nextest configuration. `make coverage` measures the - whole workspace (excluding E2E) and is only for that requested scope. - - Collect only metrics the report supports. Missing branch/changed-line - coverage is unknown, not zero. - - If measurement cannot run, continue with code-based test proposals and - mark measured coverage unverified; do not invent a coverage percentage. - -3. Rank highest-risk gaps - - Prioritize changed code, branch coverage gaps, and low-confidence boundaries. - - Apply the risk rubric in [coverage-prioritization.md](references/coverage-prioritization.md). - - Report up to 5–8 evidenced gaps; do not pad a small scope. - - For each gap, capture: file, lines, uncovered branches, and estimated risk score. - -4. Propose high-impact tests - - For each gap, name the behavior and regression, distinguishing assertions, - relevant normal/edge/failure cases, necessary setup, and estimated effort. - - Include only scenarios and setup that apply; reuse shared fixture details. - -5. Close with validation plan - - State which gaps remain after proposals. - - Give a scoped verification command and behavior-based acceptance criterion; - use a coverage threshold only when the task or repository requires one. - - List assumptions or blockers (environment, fixtures, flaky dependencies). - -## Report - -Summarize the supported metrics, then combine each ranked gap with its proposed -test and validation. Include source lines only when supplied or inspected; -mark missing metrics or locations as unknown. Do not duplicate gaps and tests -in separate templates or fill empty categories for an otherwise small report. diff --git a/.agents/skills/test-coverage-improver/agents/openai.yaml b/.agents/skills/test-coverage-improver/agents/openai.yaml deleted file mode 100644 index d3440c04d..000000000 --- a/.agents/skills/test-coverage-improver/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Test Coverage Improver" - short_description: "Find top uncovered risk areas and propose high-impact tests." - default_prompt: "Use $test-coverage-improver to analyze coverage for the requested scope, reuse matching reports, and propose tests for evidenced risks." diff --git a/.agents/skills/test-coverage-improver/references/coverage-prioritization.md b/.agents/skills/test-coverage-improver/references/coverage-prioritization.md deleted file mode 100644 index 8d8aac0d5..000000000 --- a/.agents/skills/test-coverage-improver/references/coverage-prioritization.md +++ /dev/null @@ -1,25 +0,0 @@ -# Coverage Gap Prioritization Guide - -Use this rubric for each uncovered area. - -Score = (Criticality × 2) + CoverageDebt + (Volatility × 0.5) - -- Criticality: - - 5: authz/authn, data-loss, payment/consistency path - - 4: state mutation, cache invalidation, scheduling - - 3: error handling + fallbacks in user-visible flows - - 2: parsing/format conversion paths - - 1: logging-only or low-impact utilities - -- CoverageDebt: - - 0: 0–5 uncovered lines - - 1: 6–20 uncovered lines - - 2: 21–40 uncovered lines - - 3: 41+ uncovered lines - -- Volatility: - - 1: stable legacy code with few recent edits - - 2: changed in last 2 releases - - 3: touched in last 30 days or currently in active PR - -Sort by score descending, then by business impact. diff --git a/AGENTS.md b/AGENTS.md index 40706acaa..fd799b119 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,8 @@ rules. A skill cannot expand the user's requested scope or grant authorization. - Inquiry, diagnosis, review, and planning tasks are read-only unless the user explicitly requests changes. +- Ordinary diff/commit reviews use the finding standard below directly; no + generic review skill is required. PR and high-risk reviews retain their workflows. - For implementation, read the relevant code, tests, and local guidance, then make the smallest change that satisfies the request. - State assumptions only when they affect behavior or verification. Ask only @@ -88,6 +90,9 @@ runtime/build output: - Run `cargo fmt --all --check` for Rust changes. - Run the narrowest test that exercises the changed behavior. +- For an explicitly requested coverage assessment, use the + [coverage guide](docs/testing/README.md#coverage); a regression test alone does + not require coverage measurement. - Add package-scoped `cargo check` or Clippy only for targets, features, public APIs, error handling, or control flow not compiled by the focused test. - Use `make pre-commit` only when its repository-wide fast checks add confidence @@ -150,13 +155,18 @@ For every added or edited `tracing` call: - Reuse the module's `EVENT_*`, `LOG_COMPONENT_*`, and `LOG_SUBSYSTEM_*` constants and field shape. -- Put fields first and a short label last. +- Put stable fields first (`event`, `component`, `subsystem`, `state`/`result`, + then context when available) and a short label last. - Use `error` for behavior/security failure, `warn` for degradation/fallback, `info` for low-frequency lifecycle, `debug` for diagnostics, and `trace` for repetitive request/object success paths. -- Never log secrets, credential payloads, or merged configs. +- Never log secrets, credential payloads, raw untrusted bodies, or merged configs, + including through error strings and `Debug` output. +- Prefer one aggregate summary over inventories or startup banners. -Use `.agents/skills/rustfs-logging-governance/SKILL.md` for logging changes. +Run `./scripts/check_logging_guardrails.sh` for changed logging sites. For a broad +logging audit, event-model migration, or guardrail expansion, read +[logging governance](docs/operations/logging-governance.md). ## Cross-Cutting Storage Invariants diff --git a/docs/README.md b/docs/README.md index 44f360292..af1fa9e7f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,9 @@ collection: ## Operations +- [Architecture guard troubleshooting](operations/architecture-guard-troubleshooting.md) — diagnose repository guard failures. +- [Logging governance](operations/logging-governance.md) — broad event audits, migrations, and guardrail changes. + - [Multipart upload memory diagnosis](operations/multipart-memory.md) — allocator attribution, Docker reproduction and sustained upload checks. For the logical per-operation io_uring read cap, see diff --git a/.agents/skills/arch-checks/SKILL.md b/docs/operations/architecture-guard-troubleshooting.md similarity index 89% rename from .agents/skills/arch-checks/SKILL.md rename to docs/operations/architecture-guard-troubleshooting.md index 848f8f48a..e70a16107 100644 --- a/.agents/skills/arch-checks/SKILL.md +++ b/docs/operations/architecture-guard-troubleshooting.md @@ -1,9 +1,5 @@ ---- -name: arch-checks -description: Diagnose failures from check_layer_dependencies.sh, check_architecture_migration_rules.sh, check_unsafe_code_allowances.sh, check_logging_guardrails.sh, check_doc_paths.sh, or check_no_planning_docs.sh. Use when one of these guards fails, not for every architecture question or documentation edit. ---- -# Architecture Guard Checks +# Architecture Guard Troubleshooting Read only the section for the failing guard. Use `.config/make/` and the current workflow to verify its wiring; not every guard is part of every gate. Fix the diff --git a/.agents/skills/rustfs-logging-governance/references/logging-governance.md b/docs/operations/logging-governance.md similarity index 96% rename from .agents/skills/rustfs-logging-governance/references/logging-governance.md rename to docs/operations/logging-governance.md index 4002932e3..9d8a05cdc 100644 --- a/.agents/skills/rustfs-logging-governance/references/logging-governance.md +++ b/docs/operations/logging-governance.md @@ -1,5 +1,6 @@ # Logging Audit and Migration Reference +Use the [root logging rules](../../AGENTS.md#logging) for individual events. Read this reference only for a broad logging audit, an event-model migration, or a change to `scripts/check_logging_guardrails.sh`. Use `Cargo.toml` for the current workspace/crate list instead of maintaining one here. diff --git a/docs/testing/README.md b/docs/testing/README.md index c0cd3ef35..7495d7f85 100644 --- a/docs/testing/README.md +++ b/docs/testing/README.md @@ -94,3 +94,6 @@ A flaky test fails non-deterministically without a corresponding code change. Re - `make coverage` (`.config/make/coverage.mak`) is the local equivalent; it writes `target/llvm-cov/lcov.info` and `coverage.json` and prints the same table via `scripts/coverage_per_crate.py`. - Not measured: doctests (`ci.yml` runs them uninstrumented) and the `e2e_test` crate. - A baseline change needs a linked coverage run and a reviewed explanation in the PR. +- For requested coverage assessments, reuse a report only when its revision, scope, and format match. If measurement is necessary, check disk/tool availability and use package/test-scoped `cargo llvm-cov` with the repository nextest configuration; whole-workspace measurement requires that requested scope. +- Missing branch/changed-line metrics are unknown, not zero. If measurement cannot run, mark coverage unverified and propose tests from inspected code without invented percentages. +- Rank evidenced gaps by changed behavior, data loss/security/compatibility risk, and uncovered branches. Pair each gap with a focused test, failure criterion, and scoped verification; do not introduce a threshold unless required. diff --git a/scripts/README.md b/scripts/README.md index 922f9dfe7..84984bc09 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -37,7 +37,7 @@ their issue closes. | `check_no_tokio_io_uring.sh` | ci-gate | Keeps tokio's io-uring backend disabled | ci.yml Quick Checks | | `check_s3s_footprint.sh` | ci-gate | Lower-only ratchet freezing the direct s3s surface ahead of the s3gate migration | ci.yml Quick Checks; `make pre-commit` | | `check_unsafe_code_allowances.sh` | ci-gate | Unsafe-code allowance ledger guard | ci.yml Quick Checks | -| `layer-dependency-baseline.txt` | ci-gate (data) | Committed baseline consumed by `check_layer_dependencies.sh` | arch-checks skill | +| `layer-dependency-baseline.txt` | ci-gate (data) | Committed baseline consumed by `check_layer_dependencies.sh` | [Architecture guard troubleshooting](../docs/operations/architecture-guard-troubleshooting.md) | | `static.sh` | ci-gate | Static-build helper executed inside image builds | `Dockerfile.source`, `Dockerfile.decommission-local` | | `helm_chart_version.sh` | ci-gate | Keeps the Helm chart version in sync with the release | helm-package.yml | | `test_helm_templates.sh` | ci-gate | Helm template rendering test | helm-package.yml |