---
name: semantic-versioning
description: SemVer 2.0.0 disipline — public surface tanımı (lib/REST/gRPC/event/DB/CLI), breaking change taxonomy, bump decision tree, pre-release tags (alpha/beta/rc), multi-version support policy, deprecation workflow (T-90/T-30/T-7/T-0 + RFC 8594 Sunset + RFC 9745 Deprecation header), monorepo strategy (independent vs fixed vs CalVer), tooling (semantic-release/changesets/release-please/goreleaser), CI breaking detect (openapi-diff/buf).
---

# Semantic Versioning

## Ortak Doktrin

`agents/shared/severity-rubric.md` ve `agents/shared/escalation-matrix.md`
default-load sayılır (`agents/coordination.md` §11). Bu skill'in çıktısı
**Critical / High / Medium / Low + kanıt** formatında olmak zorunda — spekülatif
Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği
aşılırsa **kullanıcı onayı zorunlu**.

## Felsefe

- **MAJOR.MINOR.PATCH = kontrat.**
- **Public surface tanımlı** — sadece public SemVer'e tabi.
- **Breaking change taxonomy** — sessiz değişiklik yasak.
- **Deprecation window** measured (T-90 default).
- **Pre-release tags** explicit.
- **Tooling otomatik** — manual hata kaynağı.

## Ne Zaman Kullanılır

- Release readiness (`/release-plan` ile birlikte)
- Breaking change kararı (major bump değerlendirme)
- Public API ilk 1.0.0 mile-stone
- Monorepo versioning strategy seçim
- Deprecation workflow başlangıcı
- Multi-version support policy yazılım
- Schema Registry (events.X.v1 → v2) major bump koordinasyon
- CI breaking detect gate kurulum
- 0.y.z'den 1.0.0'a geçiş

## Workflow

### 1) Public surface tanımı

| Surface | Tanım |
|---|---|
| Library | exported functions/classes/types/modules |
| REST API | path + method + req/res schema + headers + status |
| gRPC | proto messages/services/methods + field numbers |
| Event | topic + payload + headers + ordering |
| Database | table/column/type/constraint/index |
| CLI | command + flag + arg + exit code + stdout |

NOT surface: internal, `_private`, performance, log format.

`docs/public-surface.md` doc:

```markdown
# Public Surface — @acme/api-svc

## REST API (SemVer kapsamı)
- /v1/orders/* (GET, POST, PATCH)
- /v1/refunds/* (POST)
- Headers: Authorization, Idempotency-Key, X-Request-Id

## NOT surface
- /internal/* (intra-cluster)
- /__debug__ (dev only)
- Log format
```

### 2) Bump decision

```text
1. Public surface'te değişiklik var mı?
   - hayır → patch
   - evet → 2

2. Breaking change (taxonomy)?
   - hayır → minor
   - evet → 3

3. Deprecation window ≥ 90g doldu mu?
   - hayır → minor (deprecated marker; sonra major)
   - evet → major
```

### 3) Breaking change detect (CI)

**OpenAPI**:

```bash
npx @openapitools/openapi-diff@2 \
  --fail-on-incompatible \
  spec-base.yaml spec-head.yaml
```

**Proto**:

```bash
buf breaking --against ".git#branch=main"
# breaking detection rules: PACKAGE, FILE, WIRE_JSON
```

**Conventional Commits**:

```bash
if git log $BASE..HEAD --format='%B' | grep -E "^BREAKING CHANGE|!:"; then
  echo "Breaking change marker found — major bump required"
fi
```

### 4) Pre-release tags

```text
1.0.0-alpha.1 → alpha.2 → ... → beta.1 → rc.1 → 1.0.0
```

**alpha**: internal test; breaking kabul; production yasak.
**beta**: feature complete; breaking → fix; production opt-in feature flag.
**rc**: ship-ready; sadece Sev1 fix; production canary.
**stable**: SemVer disipline başlar.

### 5) Multi-version support

`docs/support-policy.md`:

```markdown
## Sürüm politikası
- Current (3.x): full support, weekly release
- LTS (2.x): security + Sev1 backport, 18 ay
- EOL (1.x): no patch (2025-12-31 EOL'd)
- Pre-1.0: support yok (alpha/beta/rc)
```

### 6) Deprecation workflow

| T | Aksiyon | Sahip |
|---|---|---|
| T-90 | Deprecation header + changelog `[Deprecated]` + doc warning + email customer | @release-manager |
| T-30 | Reminder (email + status page + in-app banner) | @release-manager |
| T-7 | Final reminder + onboarded customer migrate check | @api-team |
| T-0 | Remove (major bump); Sunset header pre-removal son 7g | @api-team |

HTTP header:

```http
HTTP/1.1 200 OK
Deprecation: Sun, 11 Aug 2026 00:00:00 GMT
Sunset: Tue, 11 Nov 2026 00:00:00 GMT
Link: <https://docs.acme.com/migration/v2>; rel="successor-version"
Link: <https://docs.acme.com/deprecation/api-v1>; rel="deprecation"
```

### 7) Tooling kur

**semantic-release** (Node):

```json
// .releaserc.json
{
  "branches": [
    "main",
    { "name": "beta", "prerelease": true },
    { "name": "alpha", "prerelease": true }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]"
      }
    ]
  ]
}
```

**changesets** (yarn workspaces):

```bash
yarn changeset                  # PR'a changeset ekle
yarn changeset version          # bump + changelog
yarn changeset publish          # npm + tag
```

**goreleaser**:

```yaml
# .goreleaser.yaml
builds:
  - { binary: api-svc, env: [CGO_ENABLED=0], goos: [linux, darwin], goarch: [amd64, arm64] }
archives:
  - { format: tar.gz }
checksum: { name_template: 'checksums.txt' }
release:
  github: { owner: acme, name: api-svc }
```

### 8) Monorepo strategy

| Strategy | When |
|---|---|
| Independent (changesets) | Multiple consumer; bağımsız adoption |
| Fixed (lerna fixed) | Tek mental model gerek; tüm package aynı |
| CalVer | No consumer API; internal SaaS |

Plugin default: **independent** + changesets.

### 9) Changelog discipline

Keep-a-changelog format:

```markdown
## [1.4.0] - 2026-05-11

### Added
- POST /v1/refunds endpoint (#1234)

### Changed
- Default request timeout raised 5s → 10s (#1235)

### Deprecated
- GET /v1/legacy-export — removed in v2.0.0 (Sunset 2026-08-11)

### Fixed
- Order status transition race condition (#1236)

### Security
- CVE-2026-13245 patch (envoy 1.19 → 1.21)
```

### 10) Release tag + GH release

```bash
git tag -a v1.4.0 -m "v1.4.0 — Refunds API + extended timeout"
git push origin v1.4.0
gh release create v1.4.0 --notes-file release-notes/v1.4.0.md
```

## Checklist

- [ ] `docs/public-surface.md` yazılı + sahip
- [ ] Bump decision tree dokümante
- [ ] Breaking change CI gate (openapi-diff + buf + commitlint)
- [ ] Pre-release branches (`beta`, `alpha`) ayrı
- [ ] Multi-version support policy
- [ ] Deprecation workflow (T-90/T-30/T-7/T-0)
- [ ] Tooling kurulu (semantic-release / changesets / release-please / goreleaser)
- [ ] CHANGELOG keep-a-changelog format
- [ ] Tag + GH release her sürüm
- [ ] Schema Registry coordination (event/gRPC)
- [ ] Monorepo strategy explicit

## Antipattern

- **Public surface tanımsız**.
- **Sessiz breaking** (major bump'sız).
- **0.y.z production sustained**.
- **MAJOR yıllarca bump'sız**.
- **Patch'te new feature**.
- **Pre-release production customer-facing**.
- **CHANGELOG `Misc / Updates`**.
- **Deprecation window yok**.
- **CalVer'i SemVer sanmak**.
- **Schema Registry major bump'sız breaking**.
- **Monorepo karışık strategy**.
- **Tag yok**.
- **Release notes boş**.

## Örnek Agent Davranışı

```text
User: /release-plan (yeni endpoint + bir endpoint deprecate)
Agent (release-manager + api-contract-guardian):
1. Public surface check: 2 değişiklik (yeni POST /v1/refunds, deprecated GET
   /v1/legacy-export).
2. Bump decision:
   - POST /v1/refunds → minor (yeni endpoint, optional add)
   - GET /v1/legacy-export → deprecate (T-90 marker); SemVer'de bu **minor**
     çünkü endpoint hala çalışıyor; major v2.0.0 T+90 sonra.
3. Karar: v1.3.x → **v1.4.0** (minor).
4. CI gate openapi-diff: BC ✓ (no breaking).
5. Deprecation header eklendi (Sun 2026-08-11), Sunset (Tue 2026-11-11),
   Link rel="successor-version".
6. CHANGELOG.md update: Added + Deprecated section.
7. Tag v1.4.0; GH release notes.
8. Customer email T-90 + status page banner.
9. T-90 schedule reminder (CronJob): T-30 reminder mailer.
10. v2.0.0 milestone (major) — GET /v1/legacy-export remove, ETA 2026-11-11.
```

## Çıktı Formatı

```markdown
# SemVer Decision: <package | service>

## Public surface
- (link to public-surface.md)

## Changes in this release
- Type: added / changed / deprecated / fixed / removed
- Breaking: yes / no

## Bump decision
- Current: X.Y.Z
- Next: X'.Y'.Z' (major / minor / patch)
- Rationale: <taxonomy + CI evidence>

## Deprecation (varsa)
- T-90 marker date
- Sunset date
- Migration path link

## CI gate
- openapi-diff: pass / fail
- buf breaking: pass / fail
- commitlint: pass / fail

## Action items
| P | Aksiyon | Sahip | Bitiş |
```