저장소 간 링크 정책

​

스펙 링크

• https://specs.optimism.io/...에 링크하고, specs 저장소의 specs/ 디렉터리 아래 파일의 GitHub blob에는 절대 링크하지 않습니다. 모든 specs/**.md 소스에는 렌더링된 페이지가 있으며, 렌더링된 페이지가 정식이자 탐색 가능한 형식입니다. (book.toml처럼 렌더링되지 않는 specs 저장소 파일에 대한 GitHub 링크는 괜찮습니다.)
• 페이지의 현재 경로를 사용합니다. 폐기된 경로(예를 들어 /experimental/fault-proof/..., 현재는 /fault-proof/...)는 specs 저장소의 book.toml에 있는 수동 관리 리디렉션 표를 통해서만 유지되며 예고 없이 사라질 수 있습니다. 린터는 그 리디렉션 표를 내장하고 있으며 사용해야 할 현재 경로를 알려 줍니다.
• 딥 앵커는 실제로 연결되어야 합니다. #frame-format 같은 앵커는 대상 페이지의 실제 제목 slug와 일치해야 합니다. 린터는 모든 스펙 앵커를 specs 소스 체크아웃 (--specs-src)과 대조하여 확인하므로, 상위 저장소에서 제목 이름이 바뀌면 조용히 죽은 프래그먼트가 되는 대신 여기서 린트 실패로 드러납니다.

​

쿼리 파라미터는 프래그먼트 앞에 둡니다

✅ https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs&utm_medium=docs#frame-format
❌ https://specs.optimism.io/protocol/derivation.html#frame-format?utm_source=op-docs&utm_medium=docs

​

소스 코드 링크

• 브랜치를 따라가는 링크(.../blob/develop/...)가 기본입니다. 이러한 링크는 코드를 따라가므로 오래된 구조를 가르치지 않습니다.
• 커밋 sha나 릴리스 태그에 고정된 링크 (.../blob/v1.1.4/..., .../blob/op-contracts/v1.6.0/..., .../blob/62c7f3b0.../...)는 고정 자체가 목적일 때 — 특정 릴리스 시점의 동작을 인용할 때 — 에만 허용되며, 같은 줄이나 바로 옆에 as of `<tag>` 배지를 붙여야 합니다.
  [OptimismPortal.sol](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.6.0/packages/contracts-bedrock/src/L1/OptimismPortal2.sol) (as of `op-contracts/v1.6.0`)
  
  배지는 독자에게 그 링크가 스냅샷임을 알려 주고, 유지 관리 점검에는 어떤 고정이 의도적인지 알려 줍니다. 배지가 없는 고정 링크는 실수로 생긴 낡은 링크로 간주되어 린터에서 실패합니다.

​

내부 링크

• 내부 페이지 링크는 루트 기준 상대 경로입니다: /chain-operators/...처럼 작성하며, ./sibling-page나 단순한 단어는 절대 사용하지 않습니다. 대상 페이지가 존재해야 합니다(또는 docs.json의 리디렉션으로 처리되어야 합니다).
• 정적 자산은 public/ 접두사를 포함하여 문서 루트 기준 디스크 경로로 참조합니다: /public/img/....

​

린터

# from docs/public-docs/
node scripts/lint-link-policy.mjs --baseline scripts/lint-link-policy.baseline.json

# with specs anchor resolution
git clone --depth 1 https://github.com/ethereum-optimism/specs.git /tmp/specs
node scripts/lint-link-policy.mjs --specs-src /tmp/specs --baseline scripts/lint-link-policy.baseline.json

# verify the linter itself against its embedded self-test fixtures
node scripts/lint-link-policy.mjs --self-test