저작권 헤더 — 파일별 SPDX 라이선스 라인
각 파일타입에 적합한 주석 구문의 정규 단일 라인 헤더를 사용하여 파일별 SPDX 라이선스 식별자 마커를 정의하고 강제합니다.
다운스트림 기여자를 위한 정규 규범 참조. 본 문서는 프로젝트 명세의 저작권 및 파일 헤더 섹션(Spec §0.5 + §4.6)을 미러링합니다. 게시된 저장소와 함께 제공되는 독립형 참조입니다. 아키텍처적 근거는 ADR-0002에 기록되어 있습니다.
1. 정규 헤더 라인
생태계의 모든 해당 파일은 그 파일타입 계열의 주석 구문으로 작성된 단일 정규 SPDX 라이선스 식별자 라인으로 시작해야 합니다. 이 라인은 파일의 기계 판독 가능한 라이선스 마커입니다. 비면제 파일에 대해 그 존재는 협상 불가이며, 그 내용은 파일별로 즉흥적으로 작성되지 않고 단일 진실 공급원에 의해 지배됩니다. 전체 저작권 문서는 저장소 루트의 LICENSE 파일에 한 번만 존재합니다 — 모든 소스 파일에 복제되지 않습니다.
1.1 정보 내용 (불변)
정규 내용은 정확히 한 줄입니다:
SPDX-License-Identifier: MIT— FSFE가 유지 관리하는 REUSE 명세에 따른 기계 판독 가능한 라이선스 마커. SPDX 툴체인(reuse lint,scancode), Linux 커널 도구, 다운스트림 라이선스 스캐너가 모호함 없이 파싱합니다. 시각적 테두리가 없고 파일별 저작권, 웹사이트, 이메일, GitHub 라인도 없습니다 — 파일별 출처 정보는 설계상 단일 SPDX 라인입니다(§4 참조).
1.2 참조 형식 (#-주석 계열)
정규 텍스트 — 여기서는 #-주석 구문 형태로 작성됨 — 의 진실 공급원은 src/apothem/schemas/authorship-header.txt에 있습니다:
# SPDX-License-Identifier: MIT이 텍스트가 유일한 권위 있는 공급원입니다. file-header 검증기(§7)는 이 바이트 정확 픽스처에 대해 실행됩니다. 파일의 헤더 라인과 이 픽스처 사이의 어떤 불일치(§2에 따른 구문 치환 적용 후)도 CI 실패입니다.
2. 파일타입별 변형 (바이트 정확)
라인의 정보 내용은 불변입니다. 주석 구문만 파일타입별로 달라집니다. 전체 파일타입별 변형 표:
| 파일타입 계열 | 주석 구문 | 변형 렌더링 |
|---|---|---|
# 계열 — .sh, .bash, .zsh, .py, .rb, .pl, .ps1, .yml, .yaml, .toml, .cff, .gitignore, .gitattributes, .editorconfig, .shellcheckrc, .env.example, Makefile, Dockerfile, Procfile, CODEOWNERS, PKGBUILD, scripts/apothem 같은 확장자 없는 셸 진입점 | # 라인 주석 | # SPDX-License-Identifier: MIT |
// 계열 — .js, .jsx, .mjs, .cjs, .ts, .tsx, .go, .rs, .java, .kt, .swift, .c, .cc, .cpp, .h, .hpp, .cs, .scala, .dart, .jsonc | // 라인 주석 | // SPDX-License-Identifier: MIT |
블록 주석 계열 — .html, .htm, .md, .markdown, .xml, .vue(템플릿 영역), .php(템플릿 영역) | <!-- ... --> | <!-- SPDX-License-Identifier: MIT --> |
MDX (.mdx) | {/* ... */} (JSX 표현식 주석) | {/* SPDX-License-Identifier: MIT */} |
C-블록 계열 — .css, .scss, .less, .sql (/* */) | /* ... */ | /* SPDX-License-Identifier: MIT */ |
; 계열 — .ini, .cfg, 일부 .lisp/.scm | ; 라인 주석 | ; SPDX-License-Identifier: MIT |
-- 계열 — .sql, .lua, .hs, .elm, .ada | -- 라인 주석 | -- SPDX-License-Identifier: MIT |
| 잠금 파일 / 생성된 파일 / JSON | 없음 / 해당 없음 | 면제. §3 예외 목록 참조. |
Markdown 변형 (정규 렌더링):
<!-- SPDX-License-Identifier: MIT -->HTML 주석(또는 MDX {/* */}) 래퍼는 보이지 않게 렌더링되므로, 렌더링된 표면은 깔끔하게 유지되는 동시에 소스 내 라이선스 마커는 파일타입을 막론하고 기계 판독 가능하게 유지됩니다.
3. 예외 목록 (범주적으로 면제)
다음 클래스들은 SPDX 헤더 라인에서 면제됩니다. file-header 검증기의 적용 가능성 검사는 이들에 대해 not-applicable을 반환합니다:
LICENSE— 그 자체가 법적 문서입니다.license-author-consistency검증기가 존재를 확인하는 권위 있는 저작권 라인을 담고 있습니다.*.svg에셋 — XML 주석은 라인 주석 마커에 취약하므로, SVG 출처 정보는 에셋 README와 생성된 래스터 출력으로 전달됩니다.CHANGELOG.md— 형식이 고정된 릴리스 노트 문서. SPDX 라인은 형식에 끼워 넣어지지 않고 changelog 헤더 위에 단일 HTML 주석으로 나타납니다.- JSON 파일 (
.json) — JSON에는 주석 구문이 없습니다. JSON 설정에 출처 정보가 필요한 경우 형제<file>.NOTICE.md를 배치합니다. - 잠금 파일 —
package-lock.json,yarn.lock,pnpm-lock.yaml,Cargo.lock,Pipfile.lock,poetry.lock,go.sum등 (기계 관리). - 생성된 파일 —
# Generated by ...또는// Generated by ...마커가 있는 것, 또는.gitattributes의linguist-generated=true와 일치하는 것. - 벤더링된 서드파티 콘텐츠 —
vendor/,third_party/,node_modules/아래의 파일. 이들은 업스트림 자체의 라이선스/공지를 담고 있습니다. 업스트림 저작권 표기 위에 우리 마커를 주입하는 것은 라이선스 위반입니다. .audit/파일 — gitignore된 임시 파일. 게시된 트리의 범위 밖.- 계획 파일 (
<project-root>/.apothem/plans/**, 그리고 레거시<project-root>/.plans/**) — gitignore된 임시 파일. 출처 정보는 계획의 프런트매터입니다(plans-discipline.md§3 참조). - 빈 마커 —
.keep,.gitkeep등 (의미상 0바이트). - 모든 종류의 바이너리 파일.
예외 목록 자체는 src/apothem/schemas/header-exceptions.txt에 정규식/glob 목록으로 인코딩되어 있으며 검증기의 적용 가능성 검사의 입력입니다. 수정에는 구조화된 질의와 새 ADR이 필요합니다.
4. 라이선스 상호작용
SPDX 라인은 프로젝트의 라이선스를 기계 판독 가능하게 선언하고, LICENSE 파일은 권위 있게 선언합니다:
SPDX-License-Identifier: MIT— REUSE 명세와 SPDX 표준에 따른 기계 판독 가능한 라이선스 마커. 자동화된 라이선스 스캐너가 이 라인을 직접 파싱합니다. SPDX 표현식 구문은reuse lint, scancode-toolkit, FOSSology, Linux 커널 라이선스 도구와 상호 호환됩니다.
- 저장소 루트
LICENSE— 전체 MIT 조항과 저작권자를 담고 있는 권위 있는 법적 문서. 저작권 표기의 유일한 거처입니다. 파일별 헤더는 모든 파일에 저작권을 재진술하는 대신 공유된 SPDX 식별자를 통해 이를 암묵적으로 참조합니다.
단일 라인 형식. 파일별 출처 정보는 단일 SPDX 라인입니다. 저작권 문서는 루트 LICENSE에 한 번 존재합니다. 테두리가 있는 여러 줄 배너 박스(괘선 프레임으로 감싼 저작권, 웹사이트, 이메일, 연락처 라인)는 검증기에 의해 거부됩니다: 이들은 기계 판독 가능한 라이선스 마커가 REUSE/SPDX/SBOM 도구에 이미 제공하지 않는 것을 아무것도 더하지 않으면서 모든 파일에 연락처와 저작권 메타데이터를 복제합니다. src/apothem/schemas/authorship-header.txt의 바이트 정확 픽스처는 단일 라인 형식을 담고 있으며, 검증기는 이 픽스처에 대해 실행됩니다.
상호 참조. LICENSE 파일 (MIT) — 충돌 시 법적 문서가 우선합니다. ADR-0006은 배너 축소 비준 근거를 문서화합니다.
5. 삽입 위치
- SPDX 라인은 파일의 첫 번째 내용이며, 단 하나의 예외가 있습니다: 셔뱅 라인(
#!/usr/bin/env bash,#!/usr/bin/env python3등)으로, 항상 1번 줄에 남고 SPDX 라인은 2번 줄에서 시작합니다. - YAML 프런트매터가 있는 Markdown / MDX 파일의 경우 SPDX 주석이 맨 위에 위치하고, YAML 프런트매터가 뒤따르며, 그 다음에 H1과 본문이 옵니다. 렌더링된 출력은 보이지 않는 주석으로 시작하고, 그 다음 프런트매터가 도구에 의해 파싱되고, 그 다음 보이는 내용이 흐릅니다.
- SPDX 라인과 다음 내용(프런트매터
---, 셔뱅의 후속, H1 등) 사이를 단일 빈 줄이 구분합니다.
6. 헤더 가시성 정책
특히 Markdown 파일의 경우 SPDX 라인은 기본적으로 보이지 않으며 — <!-- ... -->(또는 MDX의 경우 {/* */})로 감싸 소스에서만 보입니다. 이것이 README, CONTRIBUTING, CLAUDE.md, 지원되는 하니스 지시 파일, 스킬 SKILL.md, 명령 본문, 출력 스타일, 문서 페이지에 대한 올바른 정책입니다. 보이는 렌더링(출력 상단에 일반 텍스트 또는 펜스 블록으로 표시되는 SPDX 라인)은 즉시 읽을 수 있는 출처 정보의 혜택을 받는 독립형 참조 문서에 허용됩니다. 정책은 src/apothem/schemas/header-visibility.yaml에서 파일 클래스별로 설정되며(기본값 invisible), 라인 바로 다음에 파일 범위 재정의 마커 <!-- header-visibility: visible -->가 허용됩니다.
7. 인젝터 — scripts/inject-header.{sh,py}
다음을 수행하는 결정적 CLI:
- 하나 이상의 파일 경로(또는 glob)를 받습니다.
- 예외 목록(§3)을 통해 적용 가능성을 결정합니다.
- 기존 헤더 상태(정규 / 손상 / 부재)를 감지하고, 발견한 비정규 배너 블록을 제거하여 재실행이 멱등하도록 합니다.
- 파일타입별 올바른 SPDX 변형(§2)을 렌더링합니다.
- 셔뱅과 프런트매터를 존중하며 올바른 위치(§5)에 삽입합니다.
- 세 가지 모드로 작동합니다:
fix-in-place(쓰기),emit-patch(통합 diff 출력),check(불일치 시 exit-non-zero — CI에서 사용). - 멱등적: 두 번 실행해도 no-op.
인젝터는 SPDX 라인이 사전 삽입된 새 파일을 스캐폴딩하는 Make 타깃(make headers-fix와 make new-* 스캐폴드)과 --fix 모드의 pre-commit 훅에 의해 호출됩니다.
8. 검증기 — file-header (CI)
src/apothem/conformity/file_header_grep.py에 있습니다. 검증기는 작업 트리의 모든 파일에 대해 적용 가능성(§3에 따라)을 조회하고, 적용 가능한 경우 정규 SPDX 라인이 파일 머리에 — 다른 모든 내용보다 앞에, 유일하게 허용되는 사전 라인 내용은 셔뱅(§5) — 존재함을 단언합니다.
src/apothem/schemas/authorship-header.txt의 바이트 정확 픽스처로 뒷받침됩니다. CI 요약에 파일별 diff와 집계 커버리지 %를 보고합니다. 어떤 불일치에도 빌드를 실패시킵니다.
9. 자체 강제 메커니즘
이 규율은 향후 모든 세션과 향후 모든 기여자에서 살아남아야 합니다. 필수 강제 표면:
src/apothem/schemas/authorship-header.txt— 바이트 정확 정규 픽스처. 단일 진실 공급원.scripts/inject-header.{sh,py}— 기계적 인젝터(§7).file-headerCI 검증기(§8) — 어떤 불일치에도 빌드를 실패시킵니다.- Pre-commit 훅 — 인젝터에 연결되어 스테이지된 파일에
--fix로 검증기를 실행합니다. CLAUDE.md필수 동작 블록 — 적용 가능한 파일을 생성할 때마다 정규 SPDX 라인을 주입하도록 어시스턴트에 지시합니다.- 정규
.github/경로의 지원되는 하니스 지시 파일 — 파일 생성 시 동일하게 수행하도록 하니스 런타임에 지시합니다. src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md의 PreToolUse 훅 — 적용 가능한 경로의 Write/Edit 도구 호출을 가로채어 SPDX 라인이 나중에 CI 실패로 발견되는 대신 파일 생성 시 주입되도록 합니다.- PR 템플릿 체크박스 — 모든 새 파일이 정규 SPDX 라인을 담고 있다는 기여자 대상 단언.
- 본 문서(
site/content/docs/reference/authorship-header.mdx) — 정규 규범 설명서.
참고
- ADR-0002 — 아키텍처적 근거, 고려된 대안.
- ADR-0006 — 배너 축소 비준.
src/apothem/schemas/authorship-header.txt— 바이트 정확 정규 픽스처.src/apothem/schemas/header-exceptions.txt— 예외 목록(정규식/glob 형태).scripts/inject-header.py와scripts/inject-header.sh— 인젝터.src/apothem/conformity/file_header_grep.py— 검증기.- 프로젝트 명세 §0.5 + §4.6 — 여기서 미러링된 정규 텍스트.