semantic-versioning

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:

# 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

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:

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

Proto:

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

Conventional Commits:

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

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:

## 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/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):

// .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):

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

goreleaser:

# .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:

## [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

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ışı

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ı

# 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ş |