111 lines
3.3 KiB
Text
111 lines
3.3 KiB
Text
<!-- task=quality_improvements plan=1 tag=REFACTOR-DOC-FIX -->
|
|
|
|
# Quality Improvements — VERSIONING.md 구조 수정
|
|
|
|
## 이 파일을 읽는 구현 에이전트에게
|
|
|
|
plan=0 리뷰에서 WARN이 발생했습니다. 단일 항목만 수정합니다.
|
|
완료 후 `CODE_REVIEW.md` 검증 결과를 채우고 완료 표를 `[x]`로 갱신하세요.
|
|
|
|
## 배경
|
|
|
|
plan=0 코드 리뷰 결과, REFACTOR-4(VERSIONING.md)에서 `## nonce Overflow` 섹션이
|
|
`## Non-breaking Protocol Changes` 헤더 바로 아래에 삽입되어 구조가 깨졌습니다.
|
|
|
|
현재 구조:
|
|
```
|
|
## Non-breaking Protocol Changes
|
|
← 내용 없음
|
|
## nonce Overflow
|
|
...
|
|
|
|
Examples of non-breaking changes: ← nonce Overflow 섹션 아래에 위치 (의미상 오류)
|
|
```
|
|
|
|
의도한 구조:
|
|
```
|
|
## Non-breaking Protocol Changes
|
|
|
|
Examples of non-breaking changes:
|
|
...
|
|
|
|
Backward-compatible message additions ...
|
|
|
|
## nonce Overflow
|
|
...
|
|
```
|
|
|
|
---
|
|
|
|
### [DOC-FIX-1] VERSIONING.md `## nonce Overflow` 위치 이동
|
|
|
|
**문제**
|
|
|
|
`## nonce Overflow`가 `## Non-breaking Protocol Changes` 바디(Examples 목록, 후속 단락)보다 앞에 위치해
|
|
"Examples of non-breaking changes:" 목록이 nonce Overflow 섹션에 속한 것처럼 렌더링됩니다.
|
|
|
|
**해결 방법**
|
|
|
|
`## nonce Overflow` 블록 전체를 `Backward-compatible message additions require ...` 단락 뒤로 이동합니다.
|
|
|
|
목표 구조 (`VERSIONING.md` 하단):
|
|
|
|
```markdown
|
|
## Non-breaking Protocol Changes
|
|
|
|
Examples of non-breaking changes:
|
|
|
|
- Adding a new protobuf message type.
|
|
- Adding optional fields to application messages when older peers can ignore them.
|
|
- Adding a new language implementation that passes the existing protocol and cross-language tests.
|
|
- Tightening tests or documentation without changing wire behavior.
|
|
|
|
Backward-compatible message additions require updated parser maps and cross-language tests before release.
|
|
|
|
## nonce Overflow
|
|
|
|
`nonce` and `responseNonce` fields are protobuf `int32` values (signed 32-bit).
|
|
Overflow occurs after about 2.1 billion sends on a single connection.
|
|
|
|
Current policy:
|
|
|
|
- The protocol does not define overflow behavior. Reaching the int32 limit on a single connection is not realistic.
|
|
- Implementations do not add recovery logic for overflow.
|
|
- If overflow handling is needed in the future, the protocol version will be bumped and wrap-around behavior will be specified.
|
|
```
|
|
|
|
**수정 파일 및 체크리스트**
|
|
|
|
- [x] `VERSIONING.md` — `## nonce Overflow` 섹션을 `## Non-breaking Protocol Changes` 바디 아래로 이동
|
|
|
|
**테스트 작성**
|
|
|
|
문서 전용 변경이므로 테스트 불필요.
|
|
|
|
**중간 검증**
|
|
|
|
```bash
|
|
grep -n "^##" VERSIONING.md
|
|
# Non-breaking Protocol Changes가 nonce Overflow보다 먼저 나와야 하고
|
|
# Examples of non-breaking changes: 가 Non-breaking Protocol Changes 섹션 안에 있어야 함
|
|
grep -n "Examples of non-breaking" VERSIONING.md
|
|
grep -n "nonce Overflow" VERSIONING.md
|
|
# Examples 줄 번호 < nonce Overflow 줄 번호
|
|
```
|
|
|
|
---
|
|
|
|
## 수정 파일 요약
|
|
|
|
| 파일 | 항목 |
|
|
|------|------|
|
|
| `VERSIONING.md` | DOC-FIX-1 |
|
|
|
|
## 최종 검증
|
|
|
|
```bash
|
|
grep -n "^##" VERSIONING.md
|
|
# 섹션 순서 확인: Non-breaking Protocol Changes → nonce Overflow → New Language Compatibility
|
|
grep -A 5 "Non-breaking Protocol Changes" VERSIONING.md
|
|
# 바로 아래에 Examples 또는 설명이 와야 함 (nonce Overflow 아님)
|
|
```
|