review-followup Wave 3 라운드 1(P16): 빌드 게이트 정리 — JPA evidence manifest 폐기, build-tools 제거, API surface를 leaf check로
- 결정 4: JPA evidence·qualification manifest 폐기 → persistence-jpa 테스트, build-tools included build 비움(verifyEnvKeys는 app-bootstrap 태스크, 구현은 build-logic `ca.config-contract`), gRPC release gate 삭제 - 결정 20: API surface 검사를 leaf `check`로, JPA adopter 검사를 `ca.api-surface`로 합침(구현 하나) - 레인 단계 정리(문서 대조 레인은 `mainStage()`), integrationCheck가 입력 없는 레인을 이름과 함께 제외 → 로컬 통과(NEW-16) - release workflow 통합, releaseCheck는 tag 전용, build-logic 비핵심 플러그인 정리, sample을 ArchUnit 대상에 - 보류 4행(B3 변경 모듈만 실행, C 이미지 서명, messaging 카드 검증 이동 2행 — 결정 필요), 남음 2행(O3-5 나머지) - 통합: P17이 옮긴 gRPC release gate 사본 삭제, `grpc-proto-buf`를 release-gate needs에(P17-new-3) 검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail 통과(685 task), mainCheck 통과(268 task), -p optional-platforms ci 통과, -p build-logic test 78건 통과(손상된 TestKit 캐시 삭제 후) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
3e2cbd54f1
commit
ee4b243fe0
@@ -29,7 +29,9 @@ production unapproved — because the remedy differs in each case.
|
||||
**Promotion evidence is per capability.** `GrpcAdvancedPromotionEvidence` is one record per
|
||||
capability, so no promotion can drag another along;
|
||||
`GrpcAdvancedPromotionGate.capabilitiesDraggedAlong` returns an empty list, and that is a tested
|
||||
property rather than a claim. Two thresholds: seven days of soak plus complete evidence for
|
||||
property rather than a claim. (2026-09-28: the gate classes were removed because nothing outside
|
||||
their own tests called them — review 2026-09-24 S5-lead-4. The per-capability rule stands as a
|
||||
review rule in `docs/runbooks/grpc-advanced-capabilities.md`.) Two thresholds: seven days of soak plus complete evidence for
|
||||
`ADVANCED_STABLE`, thirty for a Stable default, because the second means every deployment gets the
|
||||
capability's dependencies and its failure modes.
|
||||
|
||||
|
||||
@@ -4,8 +4,10 @@ What the Stable gRPC platform (`:grpc:*`) is certified against, what it is only
|
||||
what is merely watched. The distinction is the point: "works with Spring Boot" is not a statement
|
||||
anyone can act on.
|
||||
|
||||
`GrpcCompatibilityMatrix.caSkeleton()` is the machine-readable form of this table, and
|
||||
`GrpcStableReleaseGate` blocks a release when a certified lane has no result or a failing one.
|
||||
The release gate is the `grpc-stable-release-gate` job in `.github/workflows/release.yml`: each
|
||||
certified lane is a strict test lane that fails when it runs nothing. The in-code
|
||||
`GrpcCompatibilityMatrix`/`GrpcStableReleaseGate` pair was removed (review 2026-09-24 S5-lead-4):
|
||||
no production or build code called it, so it gated nothing.
|
||||
|
||||
## Lanes
|
||||
|
||||
|
||||
@@ -84,12 +84,11 @@ rather than retrying a failure.
|
||||
|
||||
## Promoting a capability
|
||||
|
||||
`GrpcAdvancedPromotionGate.evaluate` names every missing item. Promotion to `ADVANCED_STABLE` needs
|
||||
compatibility evidence, a security review, fault evidence, performance evidence, an ADR, a runbook, a
|
||||
real-environment test and seven days of soak. A Stable default needs thirty.
|
||||
|
||||
Promotions are independent: promoting one capability changes no other's grade, and
|
||||
`GrpcAdvancedSupportMatrix.apply` refuses a decision made against a different matrix state.
|
||||
Promotion to `ADVANCED_STABLE` needs compatibility evidence, a security review, fault evidence,
|
||||
performance evidence, an ADR, a runbook, a real-environment test and seven days of soak. A Stable
|
||||
default needs thirty. Promotions are independent: promoting one capability changes no other's
|
||||
grade. This is a review checklist; the in-code `GrpcAdvancedPromotionGate` that restated it was
|
||||
removed (review 2026-09-24 S5-lead-4) because nothing but its own test called it.
|
||||
|
||||
Before citing a suite as evidence, check that it ran against the real infrastructure it needs (proxy,
|
||||
container, control plane or toolchain). A suite that ran without it passed and established nothing.
|
||||
|
||||
@@ -53,9 +53,10 @@ property key는 `ca-skeleton.grpc.advanced.<capability>.enabled`이고 전부
|
||||
|
||||
## Promotion은 capability별로 독립이다
|
||||
|
||||
`GrpcAdvancedPromotionEvidence`는 capability마다 별도 레코드다. 공유 레코드였다면 하나를 승격할 때
|
||||
같은 시점에 측정된 다른 것들이 함께 승격된다. `GrpcAdvancedPromotionGate.capabilitiesDraggedAlong`이
|
||||
항상 빈 리스트인 것은 주석이 아니라 테스트되는 속성이다.
|
||||
승격 증거는 capability마다 따로 판단한다. 공유 증거였다면 하나를 승격할 때 같은 시점에 측정된 다른
|
||||
것들이 함께 승격된다. 이 규칙을 코드로 옮겨 두었던 `GrpcAdvancedPromotionGate`는 자기 테스트 말고
|
||||
호출처가 없어 삭제했다(리뷰 2026-09-24 S5-lead-4). 지금은 `docs/runbooks/grpc-advanced-capabilities.md`의
|
||||
리뷰 규칙이다.
|
||||
|
||||
승격 문턱은 두 개다: `ADVANCED_STABLE`은 7일 soak + 전체 증거, Stable default는 30일 soak. 두 번째가
|
||||
더 높은 이유는 모든 배포가 그 의존성과 장애 모드를 갖게 되기 때문이다.
|
||||
|
||||
-50
@@ -1,50 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.release;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Whether one capability moves to a new grade.
|
||||
*
|
||||
* <p>Carries the grade it would move to as well as the blockers, so a refusal says what was being
|
||||
* asked for. "Not promoted" is ambiguous between a failed promotion to Advanced Stable and a failed
|
||||
* promotion to a Stable default, and the second is a much larger decision.
|
||||
*/
|
||||
public record GrpcAdvancedPromotionDecision(
|
||||
GrpcAdvancedCapability capability,
|
||||
GrpcCapabilityGrade from,
|
||||
GrpcCapabilityGrade to,
|
||||
boolean promoted,
|
||||
List<String> blockers) {
|
||||
|
||||
/** Requires blockers exactly when refused. */
|
||||
public GrpcAdvancedPromotionDecision {
|
||||
if (capability == null || from == null || to == null || blockers == null) {
|
||||
throw new IllegalArgumentException(
|
||||
"a promotion decision names its capability and both grades");
|
||||
}
|
||||
blockers = List.copyOf(blockers);
|
||||
if (promoted && !blockers.isEmpty()) {
|
||||
throw new IllegalArgumentException("a granted promotion has no blockers");
|
||||
}
|
||||
if (!promoted && blockers.isEmpty()) {
|
||||
throw new IllegalArgumentException("a refused promotion says why");
|
||||
}
|
||||
}
|
||||
|
||||
/** A granted promotion. */
|
||||
public static GrpcAdvancedPromotionDecision grant(
|
||||
GrpcAdvancedCapability capability, GrpcCapabilityGrade from, GrpcCapabilityGrade to) {
|
||||
return new GrpcAdvancedPromotionDecision(capability, from, to, true, List.of());
|
||||
}
|
||||
|
||||
/** A refused promotion. */
|
||||
public static GrpcAdvancedPromotionDecision refuse(
|
||||
GrpcAdvancedCapability capability,
|
||||
GrpcCapabilityGrade from,
|
||||
GrpcCapabilityGrade to,
|
||||
List<String> blockers) {
|
||||
return new GrpcAdvancedPromotionDecision(capability, from, to, false, blockers);
|
||||
}
|
||||
}
|
||||
-75
@@ -1,75 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.release;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import java.time.Duration;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What one capability has behind it.
|
||||
*
|
||||
* <p>Per capability, never shared. The Stable plan's requirement that Edition, streaming, xDS,
|
||||
* gRPC-Web, Servlet and the language adapters do not gate each other only means something if their
|
||||
* evidence is separate: a shared record makes promoting one of them promote whichever others
|
||||
* happened to be measured at the same time.
|
||||
*/
|
||||
public record GrpcAdvancedPromotionEvidence(
|
||||
GrpcAdvancedCapability capability,
|
||||
boolean compatibilityEvidence,
|
||||
boolean securityReview,
|
||||
boolean faultEvidence,
|
||||
boolean performanceEvidence,
|
||||
Duration soakDuration,
|
||||
boolean architectureDecisionRecord,
|
||||
boolean runbook,
|
||||
boolean realEnvironmentTest) {
|
||||
|
||||
/** Requires a capability and a non-negative soak. */
|
||||
public GrpcAdvancedPromotionEvidence {
|
||||
if (capability == null) {
|
||||
throw new IllegalArgumentException("promotion evidence names its capability");
|
||||
}
|
||||
if (soakDuration == null || soakDuration.isNegative()) {
|
||||
throw new IllegalArgumentException("a soak duration must be present and non-negative");
|
||||
}
|
||||
}
|
||||
|
||||
/** No evidence at all, which is where a capability starts. */
|
||||
public static GrpcAdvancedPromotionEvidence none(GrpcAdvancedCapability capability) {
|
||||
return new GrpcAdvancedPromotionEvidence(
|
||||
capability, false, false, false, false, Duration.ZERO, false, false, false);
|
||||
}
|
||||
|
||||
/** Everything a promotion to Advanced Stable needs. */
|
||||
public static GrpcAdvancedPromotionEvidence complete(
|
||||
GrpcAdvancedCapability capability, Duration soakDuration) {
|
||||
return new GrpcAdvancedPromotionEvidence(
|
||||
capability, true, true, true, true, soakDuration, true, true, true);
|
||||
}
|
||||
|
||||
/** Which required items are absent, as a set a report can print. */
|
||||
public Set<String> missing() {
|
||||
Set<String> missing = new java.util.LinkedHashSet<>();
|
||||
if (!compatibilityEvidence) {
|
||||
missing.add("compatibility evidence");
|
||||
}
|
||||
if (!securityReview) {
|
||||
missing.add("security review");
|
||||
}
|
||||
if (!faultEvidence) {
|
||||
missing.add("fault evidence");
|
||||
}
|
||||
if (!performanceEvidence) {
|
||||
missing.add("performance evidence");
|
||||
}
|
||||
if (!architectureDecisionRecord) {
|
||||
missing.add("architecture decision record");
|
||||
}
|
||||
if (!runbook) {
|
||||
missing.add("runbook");
|
||||
}
|
||||
if (!realEnvironmentTest) {
|
||||
missing.add("real environment test");
|
||||
}
|
||||
return Set.copyOf(missing);
|
||||
}
|
||||
}
|
||||
-85
@@ -1,85 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.release;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
|
||||
import java.time.Duration;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Decides one capability's promotion, on its own evidence.
|
||||
*
|
||||
* <p>Two thresholds rather than one. Reaching Advanced Stable means the capability works and is
|
||||
* documented; becoming a Stable default means every deployment gets it, which additionally puts its
|
||||
* dependencies on every classpath and its failure modes in every on-call rotation. The second needs
|
||||
* the first plus a longer soak, because a capability that has run in one deployment for a week is
|
||||
* not the same claim as one that ships to all of them.
|
||||
*/
|
||||
public final class GrpcAdvancedPromotionGate {
|
||||
|
||||
/** The soak a promotion to Advanced Stable requires. */
|
||||
public static final Duration ADVANCED_STABLE_SOAK = Duration.ofDays(7);
|
||||
|
||||
/** The soak a promotion to a Stable default requires. */
|
||||
public static final Duration STABLE_DEFAULT_SOAK = Duration.ofDays(30);
|
||||
|
||||
private GrpcAdvancedPromotionGate() {}
|
||||
|
||||
/**
|
||||
* Whether {@code capability} may move from {@code from} to {@code to}.
|
||||
*
|
||||
* @throws IllegalArgumentException when the transition is not one this gate governs
|
||||
*/
|
||||
public static GrpcAdvancedPromotionDecision evaluate(
|
||||
GrpcAdvancedPromotionEvidence evidence, GrpcCapabilityGrade from, GrpcCapabilityGrade to) {
|
||||
if (evidence == null || from == null || to == null) {
|
||||
throw new IllegalArgumentException("a promotion needs evidence and both grades");
|
||||
}
|
||||
if (from == to) {
|
||||
throw new IllegalArgumentException("a promotion changes the grade");
|
||||
}
|
||||
GrpcAdvancedCapability capability = evidence.capability();
|
||||
List<String> blockers = new ArrayList<>();
|
||||
|
||||
evidence.missing().stream()
|
||||
.sorted()
|
||||
.forEach(missing -> blockers.add(capability.flagName() + " has no " + missing));
|
||||
|
||||
Duration requiredSoak =
|
||||
to == GrpcCapabilityGrade.ADVANCED_STABLE ? ADVANCED_STABLE_SOAK : STABLE_DEFAULT_SOAK;
|
||||
if (evidence.soakDuration().compareTo(requiredSoak) < 0) {
|
||||
blockers.add(
|
||||
capability.flagName()
|
||||
+ " soaked for "
|
||||
+ evidence.soakDuration().toDays()
|
||||
+ " day(s); promotion to "
|
||||
+ to
|
||||
+ " requires "
|
||||
+ requiredSoak.toDays());
|
||||
}
|
||||
if (from == GrpcCapabilityGrade.WATCH && to != GrpcCapabilityGrade.EXPERIMENTAL) {
|
||||
blockers.add(
|
||||
capability.flagName()
|
||||
+ " is WATCH, which is tracked rather than implemented; it becomes EXPERIMENTAL "
|
||||
+ "before anything else");
|
||||
}
|
||||
return blockers.isEmpty()
|
||||
? GrpcAdvancedPromotionDecision.grant(capability, from, to)
|
||||
: GrpcAdvancedPromotionDecision.refuse(capability, from, to, blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether promoting {@code promoted} would drag another capability with it.
|
||||
*
|
||||
* <p>Always empty, and the method exists so a test can assert that rather than a comment claiming
|
||||
* it: each capability's evidence is its own record, so there is no path by which one promotion
|
||||
* changes another's grade.
|
||||
*/
|
||||
public static List<GrpcAdvancedCapability> capabilitiesDraggedAlong(
|
||||
GrpcAdvancedCapability promoted) {
|
||||
if (promoted == null) {
|
||||
throw new IllegalArgumentException("a capability is required");
|
||||
}
|
||||
return List.of();
|
||||
}
|
||||
}
|
||||
-66
@@ -1,66 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.release;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
|
||||
import java.util.EnumMap;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* Every advanced capability's current grade, in one place an adopter can read.
|
||||
*
|
||||
* <p>The published answer to "is this supported". Without it the answer is inferred from whether a
|
||||
* class exists, which says only that somebody wrote it.
|
||||
*/
|
||||
public final class GrpcAdvancedSupportMatrix {
|
||||
|
||||
private final Map<GrpcAdvancedCapability, GrpcCapabilityGrade> grades =
|
||||
new EnumMap<>(GrpcAdvancedCapability.class);
|
||||
|
||||
/** A matrix at each capability's default grade. */
|
||||
public GrpcAdvancedSupportMatrix() {
|
||||
for (GrpcAdvancedCapability capability : GrpcAdvancedCapability.values()) {
|
||||
grades.put(capability, capability.defaultGrade());
|
||||
}
|
||||
}
|
||||
|
||||
/** The grade of one capability. */
|
||||
public GrpcCapabilityGrade gradeOf(GrpcAdvancedCapability capability) {
|
||||
if (capability == null) {
|
||||
throw new IllegalArgumentException("a capability is required");
|
||||
}
|
||||
return grades.get(capability);
|
||||
}
|
||||
|
||||
/**
|
||||
* Applies a granted promotion.
|
||||
*
|
||||
* @throws IllegalArgumentException when the decision's starting grade is not the current one,
|
||||
* which means two promotions raced or one was replayed
|
||||
*/
|
||||
public GrpcAdvancedSupportMatrix apply(GrpcAdvancedPromotionDecision decision) {
|
||||
if (decision == null) {
|
||||
throw new IllegalArgumentException("a decision is required");
|
||||
}
|
||||
if (!decision.promoted()) {
|
||||
return this;
|
||||
}
|
||||
GrpcCapabilityGrade current = grades.get(decision.capability());
|
||||
if (current != decision.from()) {
|
||||
throw new IllegalArgumentException(
|
||||
"capability '"
|
||||
+ decision.capability().flagName()
|
||||
+ "' is "
|
||||
+ current
|
||||
+ ", not "
|
||||
+ decision.from()
|
||||
+ "; this decision was made against a different matrix");
|
||||
}
|
||||
grades.put(decision.capability(), decision.to());
|
||||
return this;
|
||||
}
|
||||
|
||||
/** The whole matrix. */
|
||||
public Map<GrpcAdvancedCapability, GrpcCapabilityGrade> snapshot() {
|
||||
return Map.copyOf(grades);
|
||||
}
|
||||
}
|
||||
-150
@@ -1,150 +0,0 @@
|
||||
package dev.caskeleton.grpc.advanced.release;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcAdvancedCapability;
|
||||
import dev.caskeleton.grpc.advanced.bootstrap.GrpcCapabilityGrade;
|
||||
import java.time.Duration;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcAdvancedPromotionGateTest {
|
||||
|
||||
@Test
|
||||
@DisplayName("a capability with complete evidence and a full soak is promoted")
|
||||
void completeEvidencePromotes() {
|
||||
GrpcAdvancedPromotionDecision decision =
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.complete(
|
||||
GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)),
|
||||
GrpcCapabilityGrade.EXPERIMENTAL,
|
||||
GrpcCapabilityGrade.ADVANCED_STABLE);
|
||||
|
||||
assertThat(decision.promoted()).isTrue();
|
||||
assertThat(decision.blockers()).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("every missing piece of evidence is named")
|
||||
void everyMissingPieceIsNamed() {
|
||||
GrpcAdvancedPromotionDecision decision =
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
|
||||
GrpcCapabilityGrade.EXPERIMENTAL,
|
||||
GrpcCapabilityGrade.ADVANCED_STABLE);
|
||||
|
||||
assertThat(decision.blockers())
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("compatibility evidence"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("security review"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("fault evidence"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("runbook"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("real environment test"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("soaked for"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("becoming a Stable default needs a longer soak than becoming Advanced Stable")
|
||||
void theStableDefaultThresholdIsHigher() {
|
||||
GrpcAdvancedPromotionEvidence weekLongSoak =
|
||||
GrpcAdvancedPromotionEvidence.complete(GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7));
|
||||
|
||||
assertThat(
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
weekLongSoak,
|
||||
GrpcCapabilityGrade.EXPERIMENTAL,
|
||||
GrpcCapabilityGrade.ADVANCED_STABLE)
|
||||
.promoted())
|
||||
.isTrue();
|
||||
assertThat(
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
weekLongSoak, GrpcCapabilityGrade.ADVANCED_STABLE, GrpcCapabilityGrade.DISABLED)
|
||||
.blockers())
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("requires 30"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a WATCH capability becomes EXPERIMENTAL before anything else")
|
||||
void watchPromotesOnlyToExperimental() {
|
||||
assertThat(
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.complete(
|
||||
GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)),
|
||||
GrpcCapabilityGrade.WATCH,
|
||||
GrpcCapabilityGrade.ADVANCED_STABLE)
|
||||
.blockers())
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("becomes EXPERIMENTAL"));
|
||||
assertThat(
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.complete(
|
||||
GrpcAdvancedCapability.EDITION_2026, Duration.ofDays(60)),
|
||||
GrpcCapabilityGrade.WATCH,
|
||||
GrpcCapabilityGrade.EXPERIMENTAL)
|
||||
.promoted())
|
||||
.isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("promoting one capability drags none of the others with it")
|
||||
void promotionsAreIndependent() {
|
||||
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
|
||||
GrpcCapabilityGrade webBefore = matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB);
|
||||
|
||||
matrix.apply(
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.complete(
|
||||
GrpcAdvancedCapability.HEDGING, Duration.ofDays(7)),
|
||||
GrpcCapabilityGrade.EXPERIMENTAL,
|
||||
GrpcCapabilityGrade.ADVANCED_STABLE));
|
||||
|
||||
assertThat(matrix.gradeOf(GrpcAdvancedCapability.HEDGING))
|
||||
.isEqualTo(GrpcCapabilityGrade.ADVANCED_STABLE);
|
||||
assertThat(matrix.gradeOf(GrpcAdvancedCapability.GRPC_WEB)).isEqualTo(webBefore);
|
||||
assertThat(GrpcAdvancedPromotionGate.capabilitiesDraggedAlong(GrpcAdvancedCapability.HEDGING))
|
||||
.isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a decision made against a different matrix state is refused")
|
||||
void aStaleDecisionIsRefused() {
|
||||
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
|
||||
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
matrix.apply(
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.complete(
|
||||
GrpcAdvancedCapability.GRPC_WEB, Duration.ofDays(7)),
|
||||
GrpcCapabilityGrade.EXPERIMENTAL,
|
||||
GrpcCapabilityGrade.ADVANCED_STABLE)))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("made against a different matrix");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a refused promotion leaves the matrix alone")
|
||||
void aRefusedPromotionChangesNothing() {
|
||||
GrpcAdvancedSupportMatrix matrix = new GrpcAdvancedSupportMatrix();
|
||||
|
||||
matrix.apply(
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
|
||||
GrpcCapabilityGrade.EXPERIMENTAL,
|
||||
GrpcCapabilityGrade.ADVANCED_STABLE));
|
||||
|
||||
assertThat(matrix.gradeOf(GrpcAdvancedCapability.XDS))
|
||||
.isEqualTo(GrpcCapabilityGrade.EXPERIMENTAL);
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a promotion that changes nothing is refused")
|
||||
void aNoOpPromotionIsRefused() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
GrpcAdvancedPromotionGate.evaluate(
|
||||
GrpcAdvancedPromotionEvidence.none(GrpcAdvancedCapability.XDS),
|
||||
GrpcCapabilityGrade.EXPERIMENTAL,
|
||||
GrpcCapabilityGrade.EXPERIMENTAL))
|
||||
.isInstanceOf(IllegalArgumentException.class);
|
||||
}
|
||||
}
|
||||
-93
@@ -1,93 +0,0 @@
|
||||
package dev.caskeleton.grpc.release;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* Which combinations a release is certified against, and which are only watched.
|
||||
*
|
||||
* <p>The distinction is what keeps a support claim honest. "Works with Spring Boot" is not a
|
||||
* statement anyone can act on; "certified on the managed Boot platform, compatibility-checked
|
||||
* against an upstream gRPC override, and not run at all on Edition 2024" is.
|
||||
*/
|
||||
public record GrpcCompatibilityMatrix(Map<String, Lane> lanes) {
|
||||
|
||||
/** How much a combination has actually been exercised. */
|
||||
public enum Lane {
|
||||
/** Run on every release. A failure blocks. */
|
||||
CERTIFIED(true),
|
||||
/** Run, but a failure is reported rather than blocking. */
|
||||
COMPATIBILITY(false),
|
||||
/** Recorded and not run. */
|
||||
WATCH(false);
|
||||
|
||||
private final boolean blocking;
|
||||
|
||||
Lane(boolean blocking) {
|
||||
this.blocking = blocking;
|
||||
}
|
||||
|
||||
/** Whether a failure in this lane blocks a release. */
|
||||
public boolean blocking() {
|
||||
return blocking;
|
||||
}
|
||||
}
|
||||
|
||||
/** Copies the lane map. */
|
||||
public GrpcCompatibilityMatrix {
|
||||
if (lanes == null || lanes.isEmpty()) {
|
||||
throw new IllegalArgumentException("a compatibility matrix names at least one lane");
|
||||
}
|
||||
lanes = Map.copyOf(lanes);
|
||||
if (lanes.values().stream().noneMatch(Lane::blocking)) {
|
||||
throw new IllegalArgumentException(
|
||||
"a matrix with no certified lane certifies nothing; every combination is optional");
|
||||
}
|
||||
}
|
||||
|
||||
/** This repository's matrix. */
|
||||
public static GrpcCompatibilityMatrix caSkeleton() {
|
||||
return new GrpcCompatibilityMatrix(
|
||||
Map.of(
|
||||
"boot-managed-platform", Lane.CERTIFIED,
|
||||
"proto3-explicit-optional", Lane.CERTIFIED,
|
||||
"netty-shaded", Lane.CERTIFIED,
|
||||
"netty-unshaded", Lane.COMPATIBILITY,
|
||||
"upstream-grpc-java-override", Lane.COMPATIBILITY,
|
||||
"protobuf-edition-2024", Lane.WATCH,
|
||||
"protobuf-edition-2026", Lane.WATCH));
|
||||
}
|
||||
|
||||
/** The lanes whose failure blocks a release. */
|
||||
public List<String> blockingLanes() {
|
||||
return lanes.entrySet().stream()
|
||||
.filter(entry -> entry.getValue().blocking())
|
||||
.map(Map.Entry::getKey)
|
||||
.sorted()
|
||||
.toList();
|
||||
}
|
||||
|
||||
/**
|
||||
* Every blocking lane that has no result.
|
||||
*
|
||||
* @return an empty list when every certified lane ran
|
||||
*/
|
||||
public List<String> missingResults(Map<String, Boolean> laneResults) {
|
||||
if (laneResults == null) {
|
||||
throw new IllegalArgumentException("a lane result map is required");
|
||||
}
|
||||
List<String> missing = new ArrayList<>();
|
||||
blockingLanes()
|
||||
.forEach(
|
||||
lane -> {
|
||||
Boolean passed = laneResults.get(lane);
|
||||
if (passed == null) {
|
||||
missing.add("certified lane '" + lane + "' produced no result");
|
||||
} else if (!passed) {
|
||||
missing.add("certified lane '" + lane + "' failed");
|
||||
}
|
||||
});
|
||||
return List.copyOf(missing);
|
||||
}
|
||||
}
|
||||
@@ -1,42 +0,0 @@
|
||||
package dev.caskeleton.grpc.release;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Whether a Stable release may go out.
|
||||
*
|
||||
* <p>Blockers are a list rather than a boolean because a release conversation is about what is
|
||||
* missing. "The gate failed" starts a search; "the fault lane did not run and the runbook is
|
||||
* absent" starts the work.
|
||||
*/
|
||||
public record GrpcReleaseDecision(boolean approved, List<String> blockers) {
|
||||
|
||||
/** Requires blockers exactly when refused. */
|
||||
public GrpcReleaseDecision {
|
||||
if (blockers == null) {
|
||||
throw new IllegalArgumentException("a release decision lists its blockers, even when empty");
|
||||
}
|
||||
blockers = List.copyOf(blockers);
|
||||
if (approved && !blockers.isEmpty()) {
|
||||
throw new IllegalArgumentException("an approved release has no blockers");
|
||||
}
|
||||
if (!approved && blockers.isEmpty()) {
|
||||
throw new IllegalArgumentException("a refused release says why");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* An approved release.
|
||||
*
|
||||
* <p>Named {@code approve} rather than {@code approved}, which the record already uses for its
|
||||
* accessor.
|
||||
*/
|
||||
public static GrpcReleaseDecision approve() {
|
||||
return new GrpcReleaseDecision(true, List.of());
|
||||
}
|
||||
|
||||
/** A refused release. */
|
||||
public static GrpcReleaseDecision refuse(List<String> blockers) {
|
||||
return new GrpcReleaseDecision(false, blockers);
|
||||
}
|
||||
}
|
||||
@@ -1,63 +0,0 @@
|
||||
package dev.caskeleton.grpc.release;
|
||||
|
||||
import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade;
|
||||
import java.util.EnumSet;
|
||||
import java.util.LinkedHashSet;
|
||||
import java.util.Set;
|
||||
|
||||
/**
|
||||
* What a release actually has evidence for.
|
||||
*
|
||||
* <p>Graded, so a release cannot cite an in-process run as transport evidence. That substitution is
|
||||
* the easiest one to make under time pressure and the hardest to spot afterwards: the suite name
|
||||
* says "contract", the report says the platform is certified, and nothing in between records that
|
||||
* no socket was opened.
|
||||
*/
|
||||
public record GrpcReleaseEvidence(
|
||||
Set<GrpcEvidenceGrade> gradesRun,
|
||||
Set<String> certifiedCapabilities,
|
||||
boolean runbookPresent,
|
||||
boolean architectureDecisionRecordsPresent,
|
||||
boolean supportMatrixPresent) {
|
||||
|
||||
/** The grades a Stable release must have run. */
|
||||
private static final Set<GrpcEvidenceGrade> REQUIRED_GRADES =
|
||||
EnumSet.of(
|
||||
GrpcEvidenceGrade.CONTRACT,
|
||||
GrpcEvidenceGrade.TRANSPORT,
|
||||
GrpcEvidenceGrade.FAULT,
|
||||
GrpcEvidenceGrade.PERFORMANCE);
|
||||
|
||||
/** Copies both sets. */
|
||||
public GrpcReleaseEvidence {
|
||||
if (gradesRun == null || certifiedCapabilities == null) {
|
||||
throw new IllegalArgumentException("release evidence states what ran and what it certified");
|
||||
}
|
||||
gradesRun = Set.copyOf(gradesRun);
|
||||
certifiedCapabilities = Set.copyOf(certifiedCapabilities);
|
||||
}
|
||||
|
||||
/** The grades a Stable release requires. */
|
||||
public static Set<GrpcEvidenceGrade> requiredGrades() {
|
||||
return Set.copyOf(REQUIRED_GRADES);
|
||||
}
|
||||
|
||||
/** The grades that were not run. */
|
||||
public Set<GrpcEvidenceGrade> missingGrades() {
|
||||
Set<GrpcEvidenceGrade> missing = new LinkedHashSet<>(REQUIRED_GRADES);
|
||||
missing.removeAll(gradesRun);
|
||||
return Set.copyOf(missing);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether {@code capability} is backed by a grade that can establish it.
|
||||
*
|
||||
* <p>The check the whole type exists for: a TLS claim needs a run that opened a socket.
|
||||
*/
|
||||
public boolean supports(String capability) {
|
||||
if (!certifiedCapabilities.contains(capability)) {
|
||||
return false;
|
||||
}
|
||||
return gradesRun.stream().anyMatch(grade -> grade.certifies().contains(capability));
|
||||
}
|
||||
}
|
||||
-94
@@ -1,94 +0,0 @@
|
||||
package dev.caskeleton.grpc.release;
|
||||
|
||||
import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* The last check before a Stable release: every lane ran, every grade is present, and the
|
||||
* operational documents exist.
|
||||
*
|
||||
* <p>Documents are a blocker rather than a follow-up. A platform whose failure modes are {@code
|
||||
* COMPLETION_UNKNOWN} and a stream that needs a full resync is a platform whose on-call has to be
|
||||
* told what to do about them; shipping the behaviour and writing the runbook afterwards means the
|
||||
* first person to meet it is the one who has to work it out at three in the morning.
|
||||
*/
|
||||
public final class GrpcStableReleaseGate {
|
||||
|
||||
private final GrpcCompatibilityMatrix matrix;
|
||||
|
||||
/** Binds the gate to its compatibility matrix. */
|
||||
public GrpcStableReleaseGate(GrpcCompatibilityMatrix matrix) {
|
||||
if (matrix == null) {
|
||||
throw new IllegalArgumentException("a release gate needs a compatibility matrix");
|
||||
}
|
||||
this.matrix = matrix;
|
||||
}
|
||||
|
||||
/**
|
||||
* The release decision.
|
||||
*
|
||||
* @param schemaBreakages what {@code buf breaking} reported against the released schema (the CI
|
||||
* job {@code grpc-proto-buf}); empty when the schema is compatible
|
||||
*/
|
||||
public GrpcReleaseDecision evaluate(
|
||||
GrpcReleaseEvidence evidence,
|
||||
Map<String, Boolean> laneResults,
|
||||
List<String> schemaBreakages) {
|
||||
if (evidence == null || laneResults == null || schemaBreakages == null) {
|
||||
throw new IllegalArgumentException(
|
||||
"a release decision needs evidence, lanes and the schema verdict");
|
||||
}
|
||||
List<String> blockers = new ArrayList<>(matrix.missingResults(laneResults));
|
||||
|
||||
evidence.missingGrades().stream()
|
||||
.sorted()
|
||||
.forEach(
|
||||
grade ->
|
||||
blockers.add(
|
||||
grade
|
||||
+ " evidence was not produced; without it the release cannot claim "
|
||||
+ grade.certifies().stream().sorted().toList()));
|
||||
|
||||
schemaBreakages.forEach(breakage -> blockers.add("schema: " + breakage));
|
||||
if (!evidence.runbookPresent()) {
|
||||
blockers.add(
|
||||
"the operations runbook is missing; COMPLETION_UNKNOWN and FULL_RESYNC_REQUIRED are "
|
||||
+ "states an on-call has to be told what to do about");
|
||||
}
|
||||
if (!evidence.architectureDecisionRecordsPresent()) {
|
||||
blockers.add("the architecture decision records are missing");
|
||||
}
|
||||
if (!evidence.supportMatrixPresent()) {
|
||||
blockers.add("the support matrix is missing, so no combination has a stated support level");
|
||||
}
|
||||
return blockers.isEmpty()
|
||||
? GrpcReleaseDecision.approve()
|
||||
: GrpcReleaseDecision.refuse(blockers);
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a capability may be advertised as supported.
|
||||
*
|
||||
* @throws IllegalStateException when the evidence behind it is of the wrong grade
|
||||
*/
|
||||
public static void requireCertified(GrpcReleaseEvidence evidence, String capability) {
|
||||
if (evidence == null) {
|
||||
throw new IllegalArgumentException("release evidence is required");
|
||||
}
|
||||
if (!evidence.supports(capability)) {
|
||||
throw new IllegalStateException(
|
||||
"capability '"
|
||||
+ capability
|
||||
+ "' is not certified by the evidence this release produced ("
|
||||
+ evidence.gradesRun().stream().map(GrpcEvidenceGrade::name).sorted().toList()
|
||||
+ ")");
|
||||
}
|
||||
}
|
||||
|
||||
/** The matrix in force. */
|
||||
public GrpcCompatibilityMatrix matrix() {
|
||||
return matrix;
|
||||
}
|
||||
}
|
||||
-151
@@ -1,151 +0,0 @@
|
||||
package dev.caskeleton.grpc.release;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
import static org.assertj.core.api.Assertions.assertThatThrownBy;
|
||||
|
||||
import dev.caskeleton.grpc.testkit.GrpcEvidenceGrade;
|
||||
import java.util.EnumSet;
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
import org.junit.jupiter.api.DisplayName;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
class GrpcStableReleaseGateTest {
|
||||
|
||||
private final GrpcStableReleaseGate gate =
|
||||
new GrpcStableReleaseGate(GrpcCompatibilityMatrix.caSkeleton());
|
||||
|
||||
private static Map<String, Boolean> allLanesPassing() {
|
||||
Map<String, Boolean> lanes = new LinkedHashMap<>();
|
||||
GrpcCompatibilityMatrix.caSkeleton().blockingLanes().forEach(lane -> lanes.put(lane, true));
|
||||
return lanes;
|
||||
}
|
||||
|
||||
private static GrpcReleaseEvidence completeEvidence() {
|
||||
return new GrpcReleaseEvidence(
|
||||
GrpcReleaseEvidence.requiredGrades(),
|
||||
Set.of("tls", "http2", "interceptor-order", "completion-unknown", "latency"),
|
||||
true,
|
||||
true,
|
||||
true);
|
||||
}
|
||||
|
||||
private static List<String> schemaAllowed() {
|
||||
return List.of();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a release with every lane, grade and document approved goes out")
|
||||
void aCompleteReleaseIsApproved() {
|
||||
GrpcReleaseDecision decision =
|
||||
gate.evaluate(completeEvidence(), allLanesPassing(), schemaAllowed());
|
||||
|
||||
assertThat(decision.approved()).isTrue();
|
||||
assertThat(decision.blockers()).isEmpty();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a certified lane that did not run blocks the release")
|
||||
void aMissingCertifiedLaneBlocks() {
|
||||
Map<String, Boolean> missing = allLanesPassing();
|
||||
missing.remove("netty-shaded");
|
||||
|
||||
assertThat(gate.evaluate(completeEvidence(), missing, schemaAllowed()).blockers())
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("netty-shaded"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a certified lane that failed blocks the release")
|
||||
void aFailedCertifiedLaneBlocks() {
|
||||
Map<String, Boolean> failed = allLanesPassing();
|
||||
failed.put("boot-managed-platform", false);
|
||||
|
||||
assertThat(gate.evaluate(completeEvidence(), failed, schemaAllowed()).blockers())
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("boot-managed-platform"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a watch lane's absence does not block")
|
||||
void watchLanesDoNotBlock() {
|
||||
assertThat(GrpcCompatibilityMatrix.caSkeleton().blockingLanes())
|
||||
.doesNotContain("protobuf-edition-2024", "protobuf-edition-2026");
|
||||
assertThat(GrpcCompatibilityMatrix.Lane.WATCH.blocking()).isFalse();
|
||||
assertThat(GrpcCompatibilityMatrix.Lane.COMPATIBILITY.blocking()).isFalse();
|
||||
assertThat(GrpcCompatibilityMatrix.Lane.CERTIFIED.blocking()).isTrue();
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a missing evidence grade blocks and says what it would have certified")
|
||||
void aMissingGradeBlocks() {
|
||||
GrpcReleaseEvidence noFaultLane =
|
||||
new GrpcReleaseEvidence(
|
||||
EnumSet.of(
|
||||
GrpcEvidenceGrade.CONTRACT,
|
||||
GrpcEvidenceGrade.TRANSPORT,
|
||||
GrpcEvidenceGrade.PERFORMANCE),
|
||||
Set.of("tls"),
|
||||
true,
|
||||
true,
|
||||
true);
|
||||
|
||||
assertThat(gate.evaluate(noFaultLane, allLanesPassing(), schemaAllowed()).blockers())
|
||||
.anySatisfy(
|
||||
blocker -> assertThat(blocker).contains("FAULT").contains("completion-unknown"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("the operational documents are blockers, not follow-ups")
|
||||
void missingDocumentsBlock() {
|
||||
GrpcReleaseEvidence undocumented =
|
||||
new GrpcReleaseEvidence(
|
||||
GrpcReleaseEvidence.requiredGrades(), Set.of("tls"), false, false, false);
|
||||
|
||||
assertThat(gate.evaluate(undocumented, allLanesPassing(), schemaAllowed()).blockers())
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("runbook"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("architecture decision records"))
|
||||
.anySatisfy(blocker -> assertThat(blocker).contains("support matrix"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a schema that breaks a consumer blocks the release")
|
||||
void aBrokenConsumerBlocks() {
|
||||
List<String> refused =
|
||||
List.of(
|
||||
"caskeleton/grpc/common/v1/stream.proto: Field \"3\" on message \"StreamEnvelope\" deleted.");
|
||||
|
||||
assertThat(gate.evaluate(completeEvidence(), allLanesPassing(), refused).blockers())
|
||||
.anySatisfy(blocker -> assertThat(blocker).startsWith("schema:"));
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a capability may not be advertised on evidence of the wrong grade")
|
||||
void aCapabilityNeedsEvidenceOfTheRightGrade() {
|
||||
GrpcReleaseEvidence contractOnly =
|
||||
new GrpcReleaseEvidence(
|
||||
EnumSet.of(GrpcEvidenceGrade.CONTRACT),
|
||||
Set.of("tls", "interceptor-order"),
|
||||
true,
|
||||
true,
|
||||
true);
|
||||
|
||||
assertThat(contractOnly.supports("interceptor-order")).isTrue();
|
||||
assertThat(contractOnly.supports("tls")).isFalse();
|
||||
GrpcStableReleaseGate.requireCertified(contractOnly, "interceptor-order");
|
||||
assertThatThrownBy(() -> GrpcStableReleaseGate.requireCertified(contractOnly, "tls"))
|
||||
.isInstanceOf(IllegalStateException.class)
|
||||
.hasMessageContaining("not certified by the evidence");
|
||||
}
|
||||
|
||||
@Test
|
||||
@DisplayName("a matrix with no certified lane certifies nothing and is refused")
|
||||
void aMatrixWithNoCertifiedLaneIsRefused() {
|
||||
assertThatThrownBy(
|
||||
() ->
|
||||
new GrpcCompatibilityMatrix(
|
||||
Map.of("everything", GrpcCompatibilityMatrix.Lane.WATCH)))
|
||||
.isInstanceOf(IllegalArgumentException.class)
|
||||
.hasMessageContaining("certifies nothing");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user