diff --git a/STANDARDS.md b/STANDARDS.md index d01a6db..367bef4 100644 --- a/STANDARDS.md +++ b/STANDARDS.md @@ -137,10 +137,44 @@ Details: [BRAND-GUIDELINES.md](BRAND-GUIDELINES.md). | Rule | Value | |---|---| | Version scheme | [SemVer 2.0](https://semver.org/) | -| Commit format | [Conventional Commits](https://www.conventionalcommits.org/) | +| Commit format | one of the two in §5.0, declared in `CONTRIBUTING.md` | | Release tags | `v..` | | Pre-release | `-alpha.N`, `-beta.N`, `-rc.N` | -| Changelog | [Keep a Changelog](https://keepachangelog.com/) format | +| Changelog | [Keep a Changelog](https://keepachangelog.com/) format, or §5.0's prose form | + +### 5.0 Who the history is written for + +A commit convention serves either a tool that derives things from it or +a reader who has to understand it, and the two cannot be optimised at +once. Pick one deliberately, per repository, and say which in +`CONTRIBUTING.md`. Mixing them inside one repository gives neither. + +The second reader is no longer only a person. Agents read repository +history to decide what to do next, and they are on the understanding +side of this split, not the deriving side: `fix: correct banner width` +tells them nothing they could not have seen in the diff, while a body +naming what went wrong and how it was noticed is the part they cannot +reconstruct. + +| Convention | Choose it when | What you get | What you give up | +|---|---|---|---| +| [Conventional Commits](https://www.conventionalcommits.org/) + Keep a Changelog | The history is an input: release tooling derives the version, the changelog and the notes from it | Automated releases (release-please, semantic-release), machine-readable change kinds | The subject line is a type and a summary; there is no room for why | +| **Incident prose** | The history is a record someone — a person or an agent — will read later to understand a decision, and releases are cut by hand with their own guards | A subject that states the change as a sentence and a body that names the failure it answers | No automation can derive a version or notes from it; you write the changelog entry yourself | + +**Incident prose, when chosen, is a convention and not an absence of one:** + +- The subject states what changed as a sentence — not a type prefix, not + a summary of the diff. +- The body names the incident: what went wrong, how it was noticed, and + what would have caught it. A change with no incident behind it says so. +- A breaking change says so on the first line of its changelog entry, + since no machine will be reading for a `!`. +- The changelog entry is written by hand and is the release note. + +Neither is a licence to skip the other's guarantees. A repository on +incident prose still tags `v..`, still writes a +changelog entry per release, and still marks breaking changes — it just +does not expect a tool to infer them. ### 5.1 Cutting a release diff --git a/STANDARDS.tr.md b/STANDARDS.tr.md index f9c03ba..99995f5 100644 --- a/STANDARDS.tr.md +++ b/STANDARDS.tr.md @@ -140,10 +140,79 @@ Detay: [BRAND-GUIDELINES.md](BRAND-GUIDELINES.md). | Kural | Değer | |---|---| | Version şeması | [SemVer 2.0](https://semver.org/) | -| Commit formatı | [Conventional Commits](https://www.conventionalcommits.org/) | +| Commit formatı | §5.0'daki ikiden biri, `CONTRIBUTING.md`'de beyan edilir | | Release tag | `v..` | | Pre-release | `-alpha.N`, `-beta.N`, `-rc.N` | -| Changelog | [Keep a Changelog](https://keepachangelog.com/) formatı | +| Changelog | [Keep a Changelog](https://keepachangelog.com/) formatı, ya da §5.0'ın düzyazı biçimi | + +### 5.0 Geçmiş kimin için yazılıyor + +Bir commit konvansiyonu ya ondan bir şey TÜRETEN alete ya da onu +ANLAMAK zorunda olan okura hizmet eder; ikisi aynı anda optimize +edilemez. Depo başına bilinçli seç ve hangisi olduğunu `CONTRIBUTING.md`'de +söyle. Aynı depo içinde karıştırmak ikisini de vermez. + +İkinci okur artık yalnız insan değil. Ajanlar bir sonraki adıma karar +vermek için depo geçmişini okuyor ve bu ayrımın TÜRETME değil ANLAMA +tarafındalar: `fix: correct banner width` onlara diff'te zaten +göremeyecekleri hiçbir şey söylemez; neyin bozulduğunu ve nasıl fark +edildiğini adlandıran bir gövde ise yeniden kuramayacakları kısımdır. + +| Konvansiyon | Şu durumda seç | Kazandığın | Verdiğin | +|---|---|---|---| +| [Conventional Commits](https://www.conventionalcommits.org/) + Keep a Changelog | Geçmiş bir GİRDİ: sürümü, changelog'u ve notları release aleti ondan türetiyor | Otomatik release (release-please, semantic-release), makine-okunur değişim türleri | Başlık satırı bir tür ve bir özettir; "neden"e yer kalmaz | +| **Vaka düzyazısı** | Geçmiş, sonradan birinin — bir insanın ya da bir ajanın — bir kararı anlamak için okuyacağı kayıt; release'ler kendi kapılarıyla elle kesiliyor | Değişikliği cümle olarak söyleyen bir başlık ve cevap verdiği arızayı adlandıran bir gövde | Hiçbir otomasyon ondan sürüm ya da not türetemez; changelog girdisini sen yazarsın | + +**Vaka düzyazısı seçildiğinde bu bir konvansiyondur, konvansiyonsuzluk +değil:** + +- Başlık, değişikliği cümle olarak söyler — tür öneki değil, diff özeti + değil. +- Gövde vakayı adlandırır: ne bozuktu, nasıl fark edildi, neyin + yakalaması gerekirdi. Arkasında vaka olmayan değişiklik bunu söyler. +- Kıran değişiklik, changelog girdisinin İLK satırında söylenir; çünkü + `!` işaretini okuyacak bir makine yok. +- Changelog girdisi elle yazılır ve release notudur. + +Hiçbiri ötekinin garantilerini atlama ruhsatı değildir. Vaka düzyazısı +kullanan bir depo yine `v..` etiketler, yine her +release için changelog girdisi yazar, yine kıran değişikliği işaretler — +yalnızca bunları bir aletin çıkarmasını beklemez. + +### 5.1 Release kesmek + +Yukarıdaki şema bir sayının ne anlama geldiğini söyler. Burası bir +sürümün nasıl çıktığını söyler, ve her satırının bedeli ödendi. + +1. **Tek komut bütün sürüm kayıtlarını taşır, ve bir test uyuştuklarını + iddia eder.** Bir sürüm birden fazla yere yazılıyorsa, elle taşımak + BAZILARINI taşır. *Vaka: bir release paketleme metadata'sını bumpladı + ve diğer üç kaydı geride bıraktı; o release'in ürettiği her artefakt, + onu üretmemiş bir sürümle damgalandı.* +2. **Changelog girdisini tag'den ÖNCE yaz.** O, release notudur; hiçbir + şey iki kez yazılmaz. +3. **Tetik yalnızca tag'dir, ve onu push etmek insan imzasıdır.** Başka + hiçbir olay yayımlamaz. Başka hiçbir şey yayımlayabiliyor olmamalı. +4. **Hattı, düşebilecek her şey GERİ ALINAMAZ adımdan önce koşacak + şekilde sırala**, ve job'a İLK değil **SON** adımının istediği izni + ver. Paket indeksine yayım geri alınamaz ve tekrarlanamaz. *Vaka: bir + release job'ı indekse yayımladı ve ardından yazma izni olmadığı için + forge release'ini oluştururken düştü; arkasındaki bağımlı job hiç + koşmadı ve hiçbir yeniden-koşu durumu onaramadı, çünkü yükleme + tekrarlanamıyordu.* +5. **Koşunun RENGİNİ değil ARTEFAKTI doğrula** — ve **iki yönde**. Yeşil + bir koşu yarım kalmış bir release bırakabilir; kırmızı bir koşu + gayet sağlam bir sürümün üstünde durabilir. Paket indeksi sayfasını, + release sayfasını ve hattın dokunması gereken her şeyi AÇ. +6. **Prosedür aletini ADLANDIRIR, ve alet değişince yeniden okunur.** + Hattın artık yapmadığı bir adımı anlatan belge, belgesizlikten + kötüdür — çünkü izlenir. *Vaka: bir release rehberi, workflow tag'den + forge release'ini oluşturmaya başladıktan aylar sonra hâlâ operatöre + onu elle açmasını söylüyordu.* + +Başarısız bir release özel mesele değildir: bir sürüm kullanıcılara +herhangi bir hâlde ulaştıysa, bunu kimsenin okumadığı bir commit +mesajında değil, o sürümün changelog girdisinde söyle. ## 6. Repo disiplini (her ürün)