Files
messaging-library/docs/messaging/experimental-policy.md
DongHyeonka dd194784c3
main / main-check (push) Successful in 8m35s
docs: 별도 repo 라이브러리로서의 지침·작업 문서·릴리스 절차를 쓴다
옮겨 온 문서는 템플릿 안의 family를 전제로 쓰였다. 루트 지침은
하네스 뼈대의 빈 양식이고, 모듈 지침·제품 문서는 템플릿 경로
(src/platforms/messaging, src/config/…, cd src)와 템플릿 소비자
(app-bootstrap, adapter:*, composition:*)를 이 repo 안의 것처럼 부른다.

- AGENTS.md(38줄)·CLAUDE.md: 꼭 지킬 것 일곱(api 모듈 순수성, 템플릿
  타입·경로 금지, 배포 버전·적용된 migration 불변, 인증 manifest 손으로
  고치지 않기 등), 지도, 맡은 일, 검증 진입점.
- README.md: 받는 법(exclusiveContent dev.cakit), migration 위치, 지원 표
  (Boot 4.0.9, kafka-clients 4.1.2, apache/kafka:4.1.0, PostgreSQL 16,
  Java 21), 구조, 문서 지도, 서명 공개 키(지문 …A1C936D7F791F8AB,
  grpc-library와 같은 키), 이력(템플릿 2959eff0에서 filter-repo).
- CHANGELOG.md: 1.0.0 절과 템플릿 안 코드에서 옮기는 법(패키지,
  Kafka 설정 키, Gradle 좌표, 바뀌지 않는 것).
- docs/README.md, docs/work/{README,gates,release}.md,
  docs/problem-statement.md: grpc-library와 같은 모양으로, 메시징의
  인증 증거 게이트·migration 규칙·템플릿과 같이 고치는 경로를 넣었다.
  docs/vision.md는 소유자가 쓸 자리라 비워 둔다.
- messaging/AGENTS.md, docs/messaging/*, starter README: registry 경로를
  이 repo 기준으로, 템플릿 쪽 경로·타입은 「백엔드 템플릿의」로 밝혔다.
  시험이 읽는 문장(지원 표의 broker·버전, 설정 참조의 YAML)은 바꾸지
  않았다.

검증: scripts/verify.sh docs rc=0(vision.md 자리 알림만). desktop
mainCheck는 이 커밋 직전 트리에서 rc=0이었다. 문서가 시험에 읽히는
부분은 다음 desktop 실행으로 다시 본다.

Refs: design-docs repo-structure/05-library-repos.md 14.2절
2026-11-08 16:16:38 +09:00

2.4 KiB

Experimental 정책

Stable과 Experimental의 차이

Stable은 공통 Contract Suite(MessagingAdapterContract)를 변경 없이 통과한 어댑터다. 컴파일되는 어댑터가 아니라, 아래 7가지를 실제로 증명한 어댑터다.

publishesAndConfirms
returnsAmbiguousWhenConfirmIsLost
redeliversWhenSettlementIsLost
preservesMessageIdAcrossRetryAndDlq
keepsSourceUnsettledWhenDlqPublishFails
rejectsOversizedPayloadBeforeTransport
stopsAcceptingNewWorkDuringShutdown

Experimental은 아직 그 증명이 끝나지 않은 어댑터다.

현재 Experimental 어댑터는 없다. Kafka Share Group·Pulsar·NATS JetStream(Experimental), RabbitMQ, Spring Cloud Stream bridge(Optional)는 SDK 없는 seam이거나 선택할 수 없는 상태여서 2026-09-25에 삭제했다(템플릿 docs/capability-status.md 제거 표). 이 문서는 새 어댑터를 들일 때 지킬 규칙이다.

규칙

1. 기본 비활성

새 Experimental 어댑터는 자기 활성화 플래그를 가지고 기본값은 false다. 활성화하지 않으면 validator가 MessagingCapabilityUnavailableException을 던진다. Contract Suite가 아직 증명 중인 어댑터가 누군가의 기본 설정 때문에 load-bearing이 되어서는 안 된다.

2. Stable 모듈이 Experimental 모듈에 의존하지 않는다

Gradle 의존 그래프로 강제된다. Experimental leaf는 messaging-spring-boot-starter의 allowed_dependencies에 넣지 않는다.

verifyCleanArchitectureDependencies가 위반을 빌드 실패로 만든다.

3. Core 계약을 바꾸지 않는다

Experimental 어댑터는 브로커의 차이를 MessagingCapabilities로 표현할 뿐, messaging-core-api의 타입을 바꾸지 않는다.

4. 없는 기능을 광고하지 않는다

Contract Suite로 증명하지 않은 capability는 MessagingCapabilities에서 false로 둔다. false인 capability를 요구하는 profile은 startup에서 실패한다. 조용히 약화되지 않는다.

승격 조건

Experimental → Stable로 올리려면 전부 필요하다.

  1. MessagingAdapterContract 7개 테스트를 변경 없이 통과
  2. 장애 주입(연결 끊김, confirm 유실, settlement 유실) 하에서 통과
  3. 지원 브로커 버전 범위 명시 및 CI 검증
  4. support-matrix.md의 capability 표 갱신
  5. ADR 작성
  6. 기본 활성화 여부에 대한 별도 결정