gitea-admin/clash-verge-rev
1
0
Fork 0
mirror of https://github.com/clash-verge-rev/clash-verge-rev.git synced 2026-11-08 11:02:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: define development and review workflow

Browse Source
This commit is contained in:
Tunglies
2026-11-08 10:15:04 +08:00
parent 46941f9d4d
commit 70799e68b8
4 changed files with 222 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/docs-consistency.yml
+55 -8
View File
@@ -1,9 +1,7 @@
name: docs-consistency
# Guards the cross-references between the collaboration documents so the
# written contract (CONTRIBUTING, AGENTS.md, PR template) and the enforced
# policy (pr-ai-slop-review) cannot drift apart unnoticed. Advisory only:
# it informs, it does not gate merges.
# Checks routing anchors and local links in collaboration documents.
# Wording checks do not establish semantic agreement between policies.
on:
pull_request:
paths:
@@ -11,6 +9,12 @@ on:
- AGENTS.md
- CLAUDE.md
- GEMINI.md
- REVIEW.md
- src/AGENTS.md
- src-tauri/AGENTS.md
- .github/ISSUE_GUIDELINES.md
- .github/agents/agentic-workflows.md
- .github/skills/agentic-workflows/SKILL.md
- .github/PULL_REQUEST_TEMPLATE.md
- .github/workflows/pr-ai-slop-review.md
- .github/workflows/docs-consistency.yml
@@ -21,8 +25,15 @@ on:
- AGENTS.md
- CLAUDE.md
- GEMINI.md
- REVIEW.md
- src/AGENTS.md
- src-tauri/AGENTS.md
- .github/ISSUE_GUIDELINES.md
- .github/agents/agentic-workflows.md
- .github/skills/agentic-workflows/SKILL.md
- .github/PULL_REQUEST_TEMPLATE.md
- .github/workflows/pr-ai-slop-review.md
- .github/workflows/docs-consistency.yml
workflow_dispatch:
permissions:
@@ -52,17 +63,53 @@ jobs:
check CONTRIBUTING.md 'Do not pad'
check CLAUDE.md '@AGENTS.md'
check GEMINI.md 'AGENTS.md'
check AGENTS.md 'REVIEW.md#ai-context-sharing'
check REVIEW.md '## AI Context Sharing'
check CONTRIBUTING.md '(REVIEW.md)'
check .github/workflows/pr-ai-slop-review.md 'Linkage Laundering'
check .github/PULL_REQUEST_TEMPLATE.md '## Problem'
check .github/PULL_REQUEST_TEMPLATE.md '## Approach'
check .github/PULL_REQUEST_TEMPLATE.md '## Scope'
echo "All cross-document anchors are consistent."
- name: Check local documentation links
run: |
python3 - <<'PY'
import re
from pathlib import Path
from urllib.parse import unquote, urlsplit
sources = [
"AGENTS.md", "CONTRIBUTING.md", "REVIEW.md", "CLAUDE.md", "GEMINI.md",
"src/AGENTS.md", "src-tauri/AGENTS.md", ".github/ISSUE_GUIDELINES.md",
".github/PULL_REQUEST_TEMPLATE.md", ".github/workflows/pr-ai-slop-review.md",
".github/agents/agentic-workflows.md", ".github/skills/agentic-workflows/SKILL.md",
]
errors = []
for source in map(Path, sources):
text = re.sub(r"(?ms)^```.*?^```[^\n]*", "", source.read_text())
for href in re.findall(r"\]\(([^\s)]+)\)", text):
link = urlsplit(href)
if link.scheme or link.netloc:
continue
target = source.parent / unquote(link.path) if link.path else source
if not target.exists():
errors.append(f"{source}: missing target {href}")
elif link.fragment and target.suffix == ".md":
headings = re.findall(r"(?m)^#{1,6} +(.+?) *#*$", target.read_text())
anchors = {re.sub(r"[^\w -]", "", h.lower()).replace(" ", "-") for h in headings}
if unquote(link.fragment) not in anchors:
errors.append(f"{source}: missing heading {href}")
for error in errors:
print(f"::error::{error}")
if errors:
raise SystemExit(1)
print(f"Local links checked in {len(sources)} collaboration documents.")
PY
- name: How to fix a failure
if: failure()
run: |
cat <<'EOF'
An anchor phrase moved or disappeared. If you intentionally reworded
one of the collaboration documents, update the other documents (and
this check's anchor list) in the same change so the written contract
and the AI-slop policy keep telling the same story.
A routing anchor or local link is missing. Update the reference and
its target together. For intentional wording changes, update this
check's anchor list and review policy agreement separately.
EOF
AGENTS.md
+16 -3
View File
@@ -1,8 +1,8 @@
# Agent Guidelines
Instructions for AI coding agents working in this repository. Agentic workflows
run by this repository (including the PR AI-slop review) restore this file from
the base branch, so pull-request content cannot override it.
Instructions for AI coding agents working in this repository. The repository's
PR AI-slop workflow restores this file from the base branch; other review tools
may load instructions differently.
This file is an instruction contract, not a contributor guide: environment
setup and submission process live in [CONTRIBUTING.md](CONTRIBUTING.md), and
@@ -61,6 +61,19 @@ the ownership evidence the AI-slop review evaluates (see
[`template/Changelog.md`](template/Changelog.md): one line per
user-visible change, no internals.
## Task Guidance
- For development and bug fixes, follow the
[development workflow](CONTRIBUTING.md#development-workflow).
- For code review and verification of review fixes, follow [REVIEW.md](REVIEW.md).
Review is read-only unless changes are authorized; findings do not expand
that authorization to unrelated fixes, commits, pushes, or GitHub updates.
- When handing work between agents or review rounds, use the
[AI context sharing guidance](REVIEW.md#ai-context-sharing).
- Read the relevant sections and linked module rules, expanding only when the
affected behavior crosses another boundary. Routine edits do not require
multiple agents or repeated review rounds.
## Issue and PR Workflows
When drafting, triaging, splitting, or implementing from a community issue, use
CONTRIBUTING.md
+54 -3
View File
@@ -12,11 +12,11 @@ We welcome AI-assisted contributions — AI assistance itself is not a problem.
To make sure your contribution is assessed fairly:
- **Link a pre-existing issue.** Non-trivial changes should fix or implement something already reported in an issue. An issue created after the pull request is a much weaker signal than a genuine problem report.
- **Keep the diff mapped to the issue.** Every changed area should be explainable from the linked issue. Unrelated refactors, formatting churn, or dependency bumps belong in separate pull requests with their own motivation.
- **Link a pre-existing issue.** Product bug fixes and features require one; self-scoped maintenance does not. Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md) for scope, linkage, and revert references. If a required issue is missing, ask maintainers to open or approve one before implementing. Use maintainer-approved private tracking for security-sensitive fixes that cannot be reported publicly.
- **Keep the diff mapped to the scope.** Every changed area should be explainable from the linked issue or stated maintenance scope. Unrelated refactors, formatting churn, or dependency bumps belong in separate pull requests with their own motivation.
- **Describe the problem in your own words.** A short statement of what breaks or what is needed, and why this approach fixes it, is worth more than a long generated report.
- **Validate against the reported behavior.** Show how the reported problem was reproduced and confirmed fixed. Generic checklists and raw tool output are not verification.
- **Do not pad with tests or defensive code.** New tests are not expected by default. Add them only when the linked issue calls for them, keep them minimal, and explain in the pull request why each is necessary; speculative error handling and coverage of hypothetical failure modes inflate the diff without adding value.
- **Do not pad with tests or defensive code.** New tests are not expected by default. Add a minimal test when the issue or task requires it, it reproduces the reported regression, or it guards behavior whose breakage would otherwise go unnoticed. Explain why it is needed; speculative error handling and coverage of hypothetical failure modes inflate the diff without adding value.
- **Disclose AI automation.** If an AI agent produced or co-produced the change, end the pull request body with the model and effort level (for example, `Assisted by: GPT-5.6 High`; effort is optional when your tool does not report it). The PR template intentionally omits this footer; agents add it themselves. Disclosure is transparency only — it does not affect how the change is assessed.
If your pull request receives an `ai-slop` label, the fastest way to clear it is substantive: link (or ask us to create) the underlying issue, narrow the scope, or push implementation changes that respond to review feedback. Editing the pull request description alone does not change the assessment.
@@ -127,8 +127,59 @@ pnpm portable
## Contributing Your Changes
### Development Workflow
Scale the work to the change. A wording fix needs a focused diff check; a change
to configuration persistence, asynchronous state, or system networking needs
evidence for the affected behavior.
1. **Define the outcome.** Identify the triggering action, relevant platform and
configuration, and actual versus expected behavior. For a bug fix, separate
the reported symptom from the suspected cause. State what remains unknown.
2. **Trace the affected path.** Read the relevant callers, state owners, and
failure paths before editing. Follow the module rules in
[src/AGENTS.md](src/AGENTS.md) or [src-tauri/AGENTS.md](src-tauri/AGENTS.md)
where applicable. Choose a reproduction or observable check that can
distinguish the old behavior from the intended result.
3. **Make the smallest complete change.** Address the confirmed cause and its
affected instances within scope. Keep unrelated cleanup separate. Add a test
only when justified by the contribution expectations above.
4. **Verify the result.** Use the checks below that cover the changed behavior.
If reproduction is unavailable, explain the alternative evidence and its
limits rather than claiming the reported problem is confirmed fixed.
5. **Review and resolve findings.** Follow [REVIEW.md](REVIEW.md). For changes
altering concurrency, persistence, system networking, or shared-contract behavior,
seek an independent review with fresh context. Check each finding against
the code before changing it; return fixes to the implementer when working
with a separate reviewer.
### Choosing Validation
Use existing checks appropriate to the affected paths; this is not a requirement
to run every command for every change. Run commands from the repository root.
| Changed behavior | Relevant checks and evidence |
| --- | --- |
| Frontend logic or state | `pnpm lint`, `pnpm typecheck`, and existing focused tests via `pnpm test <path>`; exercise the affected user interaction. |
| Rust logic | `cargo clippy-all`, relevant Cargo tests, and the affected failure or recovery path. Platform-specific branches require checks on those platforms. |
| IPC or event contracts | `pnpm gen:contract --check`, frontend type checking, and inspection of both producers and consumers. |
| UI or native integration | Exercise the changed flow; use a screenshot for visual changes and the native app for window, Service/Core, DNS, or system-proxy behavior. |
| Documentation | Check wording, relative links, referenced commands, and consistency with the authoritative rule or implementation. |
Tie results to the code reviewed: identify the base/head commits for branch
comparisons and include task-relevant staged, unstaged, and untracked files in a
local review. Report
the command or interaction, observed result, and material gaps in the existing
conversation or PR; no separate verification report is required. Static checks,
mocks, browser previews, native runs, and remote CI establish different things.
When code changes after verification, repeat affected checks. Attribute a failure
to the baseline only after comparing the same check on the base revision.
### Before Committing
Run the applicable checks from the validation guidance above. After formatting
or generation, inspect the final diff and stage only the intended changes.
**Code quality checks:**
```bash
REVIEW.md
+97
View File
@@ -0,0 +1,97 @@
# Code Review Guidelines
Use these guidelines for technical review and verification of review fixes.
Read the sections relevant to the change; follow behavior across boundaries
instead of limiting review to the directories in the diff. Contribution scope
and test expectations remain in [AGENTS.md](AGENTS.md) and
[CONTRIBUTING.md](CONTRIBUTING.md#contribution-expectations).
## Scope and Evidence
- Identify the intended outcome and the candidate being reviewed: base/head
commits, plus task-relevant staged, unstaged, and untracked files for local
work. Inspect the actual changes and necessary callers; an author's summary
is context, not proof that the implementation works.
- Check that the change solves the reported problem without breaking adjacent
behavior. For fixes, trace the cause and confirm that the verification would
expose the original failure. Use the
[validation guidance](CONTRIBUTING.md#choosing-validation) for evidence limits.
- Separate newly introduced regressions, existing defects, intentional changes,
and unresolved hypotheses. Verify a suspected finding against reachable code
and supported configurations before presenting it as a defect.
- Prioritize correctness and user impact. Omit formatting already enforced by
tools, personal style preferences, and speculative future requirements.
Suggest simplification only when a concrete duplicate state, side effect, or
unnecessary abstraction can be removed while preserving required behavior.
## Frontend
Apply [frontend architecture rules](src/AGENTS.md). Where affected, check:
- Whether an older response or event can overwrite newer authoritative state,
including after a profile, subscription, or credential change.
- Whether navigation, mode switching, remount, reload, and application restart
preserve or reset the intended state. Check pending edits and debounced writes.
- Whether one user action duplicates commands or refreshes, and whether timers,
subscriptions, and cache entries retain the correct lifetime and identity.
## Backend
Apply [backend architecture rules](src-tauri/AGENTS.md). Where affected, check:
- What remains persisted or active after partial success, failure, or rollback,
and whether returned errors and notifications describe that actual state.
- Lock ordering, cancellation, retries, and ownership of Service/Core processes
and OS settings through startup, shutdown, disconnection, and recovery.
- Platform-specific control flow after conditional compilation. A check on one
platform does not establish correctness on the others.
## Cross-boundary Behavior
- Trace changed commands and events from producer to consumer, including
generated bindings, payload semantics, ordering, and success/error handling.
- Check that UI state follows backend outcomes, including failed mutations and
stale cache reads. Do not treat an optimistic display as proof of success.
- For DNS, proxy, updater, or service changes, inspect the affected external
state and failure path; source or mock evidence alone cannot establish native
behavior. Keep unexercised cases explicit.
## Findings and Re-review
- Report each actionable finding with a file and line, triggering conditions,
impact, supporting evidence, and whether this change introduced it. Severity
follows impact and reachability. Keep optional simplifications separate from
defects; do not turn existing issues into unrelated required fixes.
- State plainly when no actionable findings remain, together with material
verification gaps. This is a conclusion about the reviewed candidate, not a
guarantee that every runtime or platform was exercised.
- For each finding, verify the fix or explain why it is incorrect, intentional,
or outside scope. Fix confirmed instances of the same defect within the task's
scope, then recheck affected behavior.
- On re-review, compare the new candidate with the previously reviewed version.
Focus on finding closure, the repair diff, and its consequences. Expand only
when changes or new evidence affect another boundary. Keep finding identities
stable and do not repost resolved findings without new evidence.
- Stop when actionable findings are resolved and relevant checks pass; do not
require a fixed number of passes. After three rounds without convergence,
summarize the remaining evidence or disagreement and reconsider the cause,
scope, or approach before continuing. An unresolved finding is not a pass.
## AI Context Sharing
Agents own context transfer between implementation, review, repair, and re-review.
The issue supplies the human-facing problem, scope, and acceptance criteria;
maintenance without an issue uses the authorized task. Humans do not need to
prepare agent handoffs or relay findings between agents.
- Pass the task reference, candidate revision and scope, relevant source locations
and constraints, verification results, and unresolved findings. Keep this in the
working session or agent handoff; do not publish internal transcripts or require
another repository document.
- Separate observations from assumptions. Refresh stale context from source and
independently verify the relevant paths instead of inheriting another agent's
verdict. Retrieve missing code context within the authorized scope.
- The repairing agent maps each repair or non-fix rationale to its original
finding and passes the updated revision and verification results to the reviewer.
- Escalate missing requirements, unavailable external evidence, or decisions that
need human input; do not ask humans to reconstruct the implementation.