Skip to content

Repository maintenance: fix cross-link 404s, add LICENSE, CI checks, and contribution governance - #1

Merged
anneheartrecord merged 6 commits into
mainfrom
chore/maintenance-2026-08
Aug 11, 2026
Merged

Repository maintenance: fix cross-link 404s, add LICENSE, CI checks, and contribution governance#1
anneheartrecord merged 6 commits into
mainfrom
chore/maintenance-2026-08

Conversation

@anneheartrecord

Copy link
Copy Markdown
Owner

Housekeeping pass on the repo, plus two real defects found along the way.

Defects fixed

Every chapter cross-link 404'd on GitHub. All 56 of them were written as docs/<file>.md from inside docs/. With docsify's relativePath disabled those resolved from the site root, so the published site worked — but GitHub's file view resolved them to docs/docs/<file>.md. That is what anyone browsing the repo or working from a fork actually hits. Fixed by enabling relativePath and rewriting the links to same-directory relative form, correct in both contexts.

One link was dead everywhere. 12-Agent-Security-Design.md pointed at 13-啃完51万行源码的发现与Claude的封号机制.md, a filename that stopped existing when chapter 13 was renamed.

English chapter 01 was a third of the Chinese one — 5.2 KB against 15 KB — missing the source-leak background, what Claude Code is, how it differs from an agent framework, the six-step request journey, the industry comparison table, and the key-numbers table. Chapter 01 is where every English reader starts. Translated from the existing Chinese analysis: no new claims, same numbers, plus the four illustrations the Chinese side already had.

Added

  • LICENSE — MIT, which both READMEs have declared since the first release without the file ever being committed, so GitHub showed the repo as unlicensed. Includes a scope note: no Claude Code source is redistributed here, and quoted excerpts remain their owners'.
  • scripts/check_links.py — validates every local Markdown and image link and enforces the per-context link convention, so the cross-link bug cannot come back silently. Verified in both directions: passes clean on 188 links, and catches an injected broken link and an injected convention violation.
  • scripts/check_bilingual.py — pairs chapters by number, flags any that exist in one language only or whose two sides have drifted apart in size. This is what surfaced the chapter 01 gap.
  • GitHub Actions running both checks on push, on PRs, and weekly.
  • CONTRIBUTING.md / CONTRIBUTING_EN.md — states that factual corrections are wanted over new content, and sets an evidence bar: source path plus symbol, reproducible steps, or official documentation.
  • CODE_OF_CONDUCT.md — Contributor Covenant 2.1.
  • Issue templates for chapter corrections, version drift, and new chapter proposals; drift reports carry the upstream version observed. Plus a PR template.
  • Version coverage tables in both READMEs, recording which source snapshot the analysis was verified against instead of leaving readers to guess.
  • CHANGELOG.md.

Also

  • .idea/ dropped from version control.
  • The two READMEs were out of sync; the Chinese side was missing the git-history paragraph and the reproduction steps the English side had.

Verification

$ python3 scripts/check_links.py
✓ 188 local links across 32 files, all resolve

$ python3 scripts/check_bilingual.py
✓ 13 chapters, both languages present and comparable

No chapter conclusions were changed. Re-verifying chapter content against current upstream is tracked separately.

…site

Every cross-link inside docs/ was written as docs/<file>.md. With docsify's
relativePath disabled those resolved from the site root and worked on the
published site, but in GitHub's file view they resolved to docs/docs/<file>.md
and 404'd — which is what anyone browsing or forking the repo actually hits.

Switch relativePath on and rewrite the 56 chapter cross-links to same-directory
relative paths, correct in both contexts. _sidebar.md and _home.md move to
root-absolute paths, as relativePath requires.

Also fixes a link in 12-Agent-Security-Design.md pointing at
13-啃完51万行源码的发现与Claude的封号机制.md, a name that stopped existing when
chapter 13 was renamed — dead everywhere, not just on GitHub.
Both READMEs have declared MIT since the first release but no LICENSE file was
ever committed, so GitHub showed the repo as unlicensed. Adds a scope note
making explicit that no Claude Code source is redistributed here and that
quoted excerpts remain their owners'.

Also stops tracking .idea/.
check_links.py validates every local link and enforces the per-context
convention, so the class of bug fixed two commits back cannot come back
silently. check_bilingual.py pairs chapters by number and flags any that exist
in one language only or whose two sides have drifted apart in size.

Runs on push, on pull requests, and weekly — rot arrives without anyone
touching the repo.
States what this repo actually wants — factual corrections over new content —
and sets an evidence bar: a correction needs a source path plus symbol,
reproducible steps, or official documentation. Separate templates for chapter
corrections, version drift, and new chapter proposals, so drift reports carry
the upstream version they were observed in.
The English chapter 01 was a 5.2 KB summary against 15 KB of Chinese, missing
the source-leak background, what Claude Code is, how it differs from an agent
framework, the six-step request journey, the industry comparison, and the
key-numbers table. Chapter 01 is the entry point for every English reader.

Translated from the existing Chinese analysis; no new claims, same numbers.
Adds the four illustrations the Chinese side already had.
A source teardown goes stale, so state which snapshot it was verified against
instead of leaving readers to guess: source snapshot date, the version that
build self-reported, when chapters were last re-verified, and when the repo was
last maintained. Points drift at the issue template.

Syncs the two READMEs — the Chinese side was missing the git-history paragraph
and the reproduction steps the English side had.
@anneheartrecord
anneheartrecord merged commit d3844a4 into main Aug 11, 2026
1 check passed
@anneheartrecord
anneheartrecord deleted the chore/maintenance-2026-08 branch August 11, 2026 02:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant