Repository maintenance: fix cross-link 404s, add LICENSE, CI checks, and contribution governance - #1
Merged
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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>.mdfrom insidedocs/. With docsify'srelativePathdisabled those resolved from the site root, so the published site worked — but GitHub's file view resolved them todocs/docs/<file>.md. That is what anyone browsing the repo or working from a fork actually hits. Fixed by enablingrelativePathand rewriting the links to same-directory relative form, correct in both contexts.One link was dead everywhere.
12-Agent-Security-Design.mdpointed at13-啃完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.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.CHANGELOG.md.Also
.idea/dropped from version control.Verification
No chapter conclusions were changed. Re-verifying chapter content against current upstream is tracked separately.