49 lines
1.5 KiB
Markdown
49 lines
1.5 KiB
Markdown
# Requirements
|
|
|
|
각 requirement 문서는 Markdown body 앞에 JSON front matter를 둔다.
|
|
|
|
## File naming
|
|
|
|
```text
|
|
req-NNN_<slug>.md
|
|
```
|
|
|
|
- `NNN`: requirement ID의 세 자리 decimal number
|
|
- `<slug>`: requirement title을 나타내는 lowercase kebab-case ASCII slug
|
|
|
|
## Metadata schema
|
|
|
|
```json
|
|
{
|
|
"schema": "proofline.requirement/v1",
|
|
"id": "REQ-NNN",
|
|
"title": "사람이 읽는 제목",
|
|
"revision": "major.minor",
|
|
"status": "draft | approved | retired",
|
|
"depends_on": ["REQ-NNN"],
|
|
"applies_to": ["algorithm-name"],
|
|
"language": "ko"
|
|
}
|
|
```
|
|
|
|
- `id`: repository 안에서 고유한 requirement identifier
|
|
- `revision`: 사람이 읽는 requirement revision. `draft` 상태에서 본문을 수정해도 올리지 않으며, `approved` 상태로 전환할 때 또는 승인된 requirement의 의미를 변경하기 위해 재승인할 때만 올린다.
|
|
- `status`: requirement lifecycle 상태. `approved`는 명시적인 사용자 승인을 의미한다.
|
|
- `depends_on`: 선행 requirement identifier 목록
|
|
- `applies_to`: requirement가 적용되는 algorithm 또는 product 영역
|
|
|
|
## Python parsing
|
|
|
|
front matter body는 JSON이므로 별도 dependency 없이 Python 표준 라이브러리로 읽을 수 있다.
|
|
|
|
```python
|
|
import json
|
|
from pathlib import Path
|
|
|
|
text = Path("docs/requirements/req-001_algorithm-input-contract.md").read_text(encoding="utf-8")
|
|
_, metadata_json, _ = text.split("---", 2)
|
|
metadata = json.loads(metadata_json)
|
|
```
|
|
|
|
JSON front matter의 `revision`과 `status`가 문서의 단일 source of truth다.
|