diff --git a/.gitattributes b/.gitattributes index 094c0eb7..c649e826 100644 --- a/.gitattributes +++ b/.gitattributes @@ -24,3 +24,4 @@ gradlew.bat text eol=crlf # Ledger lines are only appended; a union merge keeps both branches' new lines (docs/ledger/README.md). docs/ledger/estimates.jsonl merge=union +docs/ledger/flaky-tests.jsonl merge=union diff --git a/docs/ledger/README.md b/docs/ledger/README.md index f6e01776..29fa6f8b 100644 --- a/docs/ledger/README.md +++ b/docs/ledger/README.md @@ -1,4 +1,13 @@ -# 예측·실측 장부 +# 장부 + +이 폴더에는 줄을 더하기만 하는 JSON Lines 장부가 둘 있다. + +- `estimates.jsonl`: 작업의 예측·실측(아래 절). +- `flaky-tests.jsonl`: 흔들린 시험. 흔들림 하나가 한 줄이다. 칸(`date`·`test`·`category`·`first_run`·`verdict`·`quarantined_until`·`fixed_by`)과 범주의 정본은 design-docs `ci/manual.md` 8.5절이고, 판정·처리 절차는 그 문서 8.3절이다. 고친 PR이 병합되면 그 줄의 `fixed_by`를 채운다. + +두 파일 모두 `.gitattributes`가 `merge=union`을 준다. 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않는다. + +## 예측·실측 장부 작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07). @@ -9,7 +18,6 @@ ``` - 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. -- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다. - p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다. - 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다. - 위임 대조용 장부(design-docs `delegation-loop/ledger.jsonl`)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 `task`를 가리킨다. diff --git a/docs/ledger/flaky-tests.jsonl b/docs/ledger/flaky-tests.jsonl new file mode 100644 index 00000000..fd43a389 --- /dev/null +++ b/docs/ledger/flaky-tests.jsonl @@ -0,0 +1,5 @@ +{"date": "2026-11-12", "test": "compose smoke local-messaging (scripts/run-compose-runtime-smoke.sh)", "category": "concurrency-order", "first_run": "100", "verdict": "runner nightly 구성 1회 실패: 앱이 기반 서비스가 healthy가 되기 전에 떴다. 고친 뒤 desktop matrix 18/18 통과", "quarantined_until": "", "fixed_by": "백엔드 #13"} +{"date": "2026-11-13", "test": "GrpcP1BoundaryWireTest#aSlowCallWithoutAClientDeadlineEndsAtTheServerDefaultDeadline", "category": "fixed-time", "first_run": "221", "verdict": "runner main push 4회 중 1회 실패(152·164·183 통과). desktop 1코어 고정 15회, CPU 부하 아래 24회 통과", "quarantined_until": "", "fixed_by": "백엔드 #34"} +{"date": "2026-11-13", "test": "FailureInjectionContractTest#aSlowDripThroughToxiproxyEndsAtTheTotalDeadline[JDK]", "category": "fixed-time", "first_run": "228", "verdict": "runner 1회 실패(1.92초, 상한 1.5초). desktop 부하 6.5~8에서 10회 통과(호출 1,010~1,021ms)", "quarantined_until": "", "fixed_by": "백엔드 #34"} +{"date": "2026-11-13", "test": "LiveEventLogContractTest#concurrentWritersAllocateDistinctPositions", "category": "concurrency-order", "first_run": "260", "verdict": "replay 순서를 writer 제출 순서로 단언했다. 둘째 writer를 먼저 돌린 탐침에서 재현. 고침 PR 백엔드 #39(열림)", "quarantined_until": "", "fixed_by": ""} +{"date": "2026-11-13", "test": "JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline", "category": "fixed-time", "first_run": "desktop ~/w2-reloc-logs/w2-reloc-a.log (main c7a18ec7, prCheck, 시작 부하 11~15)", "verdict": "desktop 1회 실패(1.68초, 상한 1.5초). PR 단계 test라 runner PR run에서도 날 수 있다", "quarantined_until": "", "fixed_by": ""} diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index f6757859..2dad7c50 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -149,7 +149,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') | **smoke 이미지가 이 트리에서 만들어졌음을 보이기.** smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 `CACHED`가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다. -**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다. +**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수와 각 반복을 시작할 때의 부하(`uptime`)를 적는다. runner에서 실패했으면 그 job이 돈 시각에 desktop에서 잠금 아래 돈 실행도 적는다(runner는 잠금 밖이다). 흔들림으로 판정하면 `docs/ledger/flaky-tests.jsonl`에 한 줄을 더하고, 상한을 늘리거나 재시도를 붙이지 않고 design-docs `ci/manual.md` 8.4절대로 고친다. **공유 잠금 기다리기.** 순서는 `flock`이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 `ps -o pid,etime,args -C flock`으로 쥔 쪽을 보고 맡긴 쪽에 알린다([operate.md](../operate.md) 7절). diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index f79a3cd1..c051a547 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -159,7 +159,7 @@ | 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성을 못 봄 | | `// when`이 하나인가 | 두 동작을 한 테스트가 봄 | | 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 실패한 채 방치 | -| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 | +| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언, PR·main 단계 시험의 벽시계 상한(「1.5초 안에」) 단언, 스레드 시작 순서를 결과 순서로 보는 단언. 시계 주입·조건 대기·결과 단언으로 쓴다(design-docs `ci/manual.md` 8.4절) | fake와 공유 계약: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와 실제 adapter가 같은 추상 계약(`XxxContract`)을 상속한다. 계약 밖 fake, 소비자 없는 fake, 계약과 겹친 adapter 손 사본 테스트는 만들지 않는다. fake 동작을 바꾸면 계약 케이스를 같이 바꾼다. 포트를 더하거나 계약을 옮기면 `docs/testing/TESTING_STRATEGY.md`의 현황표를 고친다. diff --git a/scripts/tests/test_ledger.py b/scripts/tests/test_ledger.py index 8d868a5e..efcc530b 100644 --- a/scripts/tests/test_ledger.py +++ b/scripts/tests/test_ledger.py @@ -1,4 +1,5 @@ -"""docs/ledger/estimates.jsonl의 줄이 docs/ledger/README.md 형식인지 본다. +"""docs/ledger/의 장부 두 파일이 정해진 형식인지 본다(estimates.jsonl은 docs/ledger/README.md, +flaky-tests.jsonl은 design-docs ci/manual.md 8.5절). python3 -m unittest discover -s scripts/tests """ @@ -7,7 +8,7 @@ from __future__ import annotations import json import unittest -from datetime import datetime +from datetime import date, datetime from pathlib import Path REPO = Path(__file__).resolve().parent.parent.parent @@ -15,6 +16,9 @@ LEDGER = REPO / "docs/ledger/estimates.jsonl" KINDS = {"estimate", "actual", "retro"} COMMON = ("schema", "kind", "task", "recorded_at") RANGES = ("minutes", "calls", "output_tokens") +FLAKY = REPO / "docs/ledger/flaky-tests.jsonl" +FLAKY_FIELDS = {"date", "test", "category", "first_run", "verdict", "quarantined_until", "fixed_by"} +FLAKY_CATEGORIES = {"fixed-time", "concurrency-order", "resource-io", "test-order", "external"} def lines() -> list[dict]: @@ -49,5 +53,19 @@ class LedgerTest(unittest.TestCase): self.assertEqual(entry["within"], expected, entry["task"]) +class FlakyLedgerTest(unittest.TestCase): + def test_every_flaky_line_has_exactly_the_manual_fields_and_a_known_category(self) -> None: + for number, line in enumerate(FLAKY.read_text(encoding="utf-8").splitlines(), start=1): + if not line.strip(): + continue + entry = json.loads(line) + self.assertEqual(entry.keys(), FLAKY_FIELDS, f"line {number}") + self.assertIn(entry["category"], FLAKY_CATEGORIES, f"line {number}") + date.fromisoformat(entry["date"]) + if entry["quarantined_until"]: + date.fromisoformat(entry["quarantined_until"]) + self.assertTrue(entry["test"].strip() and entry["verdict"].strip(), f"line {number}") + + if __name__ == "__main__": unittest.main()