From 88d35f79361a24066935c8f10e477585a8bbb316 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 19:46:21 +0900 Subject: [PATCH 1/2] =?UTF-8?q?docs(ledger):=20=ED=9D=94=EB=93=A4=EB=A6=B0?= =?UTF-8?q?=20=EC=8B=9C=ED=97=98=EC=9D=84=20=EC=9E=A5=EB=B6=80=EC=97=90=20?= =?UTF-8?q?=EB=82=A8=EA=B8=B0=EA=B3=A0=20=EC=8B=9C=EA=B0=84=C2=B7=EC=88=9C?= =?UTF-8?q?=EC=84=9C=20=EB=8B=A8=EC=96=B8=20=EA=B7=9C=EC=B9=99=EC=9D=84=20?= =?UTF-8?q?=EB=A6=AC=EB=B7=B0=20=EA=B8=B0=EC=A4=80=EC=97=90=20=EA=B1=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 2026-11-12~13 백엔드 runner에서 흔들린 시험은 넷이다. 그런데 기록이 공유 노트와 세션 메시지에 흩어져 있다. 같은 모양(벽시계 상한, 스레드 시작 순서)이 다시 들어와도 리뷰 기준에는 「스레드 없음」 단언만 적혀 있어서 막을 근거가 없다. - `docs/ledger/flaky-tests.jsonl`: 흔들림 하나가 한 줄이다. 칸과 범주의 정본은 design-docs `ci/manual.md` 8.5절이다. 첫 네 줄: - compose 기동 경쟁(run 100, #13으로 고침) - gRPC 서버 deadline(run 221, #34) - HTTP client slow drip JDK(run 228, #34) - JPA 동시 writer replay 순서(run 260, #39 열림) `.gitattributes`에 `merge=union`을 준다. `scripts/tests/test_ledger.py`가 칸·범주·날짜 형식을 본다. - review-criteria.md 「타이밍에 기대지 않나」: 벽시계 상한 단언과 스레드 시작 순서 단언을 더하고, 매뉴얼 8.4절을 가리킨다. - gates.md 「원래 있던 실패 가리기」: 반복마다 시작 부하를 적게 한다. runner 실패면 그 시각에 잠금 아래 돈 desktop 실행도 적는다(runner는 잠금 밖이다). 흔들림이면 장부에 한 줄을 더하고, 상한을 늘리거나 재시도를 붙이지 않고 8.4절대로 고친다. PR #12가 실패했다는 HTTP/2 흔들림은 넣지 않았다. 그 PR의 runner run은 모두 cancelled라 어느 시험인지 특정할 수 없다. 검증: scripts/verify.sh docs(노트북) rc=0. test_ledger의 새 시험이 잘못된 범주를 잡는지 한 줄을 바꿔 실패를 확인하고 되돌렸다. Refs: design-docs ci/03-time-reduction-plan.md FLAKY-1 --- .gitattributes | 1 + docs/ledger/README.md | 12 ++++++++++-- docs/ledger/flaky-tests.jsonl | 4 ++++ docs/work/reference/gates.md | 2 +- docs/work/reference/review-criteria.md | 2 +- scripts/tests/test_ledger.py | 22 ++++++++++++++++++++-- 6 files changed, 37 insertions(+), 6 deletions(-) create mode 100644 docs/ledger/flaky-tests.jsonl 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..32838b2c --- /dev/null +++ b/docs/ledger/flaky-tests.jsonl @@ -0,0 +1,4 @@ +{"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": ""} 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() -- 2.54.0 From 5f0bf17bd2875db1fa6265c0a607a01a9d1b8c0c Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 20:42:21 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs(ledger):=20PR=20=EB=8B=A8=EA=B3=84=20J?= =?UTF-8?q?etty=20attempt=20deadline=20=EC=8B=9C=ED=97=98=EC=9D=98=20?= =?UTF-8?q?=ED=9D=94=EB=93=A4=EB=A6=BC=EC=9D=84=20=EB=8D=94=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit desktop에서 main c7a18ec7의 prCheck를 돌렸을 때(시작 부하 11~15) JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline이 1.68초로, 상한 1.5초를 넘어 실패했다. #34가 고친 벽시계 시험 범위 밖에 남은 것이다. 고치는 일은 벽시계 시험을 맡은 쪽에 넘겼다. 검증: python3 -m unittest scripts/tests/test_ledger.py 통과. --- docs/ledger/flaky-tests.jsonl | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/ledger/flaky-tests.jsonl b/docs/ledger/flaky-tests.jsonl index 32838b2c..fd43a389 100644 --- a/docs/ledger/flaky-tests.jsonl +++ b/docs/ledger/flaky-tests.jsonl @@ -2,3 +2,4 @@ {"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": ""} -- 2.54.0