Veri API oluşturucusu için ilkeler
Hataya neden olan değişiklikler, bildirimler, sürümler ve sürüm oluşturma ile ilgili veri API oluşturucusu ilke kümesi tarafından yönetilir.
Sürüm oluşturma ve yayınlar
Data API builder bağlamındaki bir yayın , yazılımın biçimiyle Major.Minor.Patch tanımlanan yayımlanan her sürümünü ifade eder. Bu sürümler üç kategoriye ayrılır: kararlı, hataya neden olan değişiklik ve önizleme.
Kararlı sürümler
Data API builder'ın kararlı bir sürümü geriye dönük olarak uyumludur. Geriye dönük uyumlu, veri API oluşturucusunun bir sürümünü kullanan yazdığınız tüm kodların, doğruluğu veya mevcut işlevselliği korumak için kod değişikliğine gerek kalmadan daha yeni ve kararlı bir sürümü benimseyebileceğini ifade eder.
Yeni değişiklik sürümleri
Veri API oluşturucusunun hataya neden olan bir değişiklik sürümü geriye dönük olarak uyumlu değildir. Mevcut istemci kodunda hataya neden olan bir değişiklik sürümünü benimsemek, istemcinin önceki sürümü hedeflerken olduğu gibi davrandığından emin olmak için kod değişiklikleri gerektirebilir.
Hataya neden olan değişiklik sürümleri, hataya neden olan değişiklik listesi makalesi ve GitHub sürümünün değişiklik açıklaması aracılığıyla duyurulur. Değişiklikler kritik güvenlik, gizlilik veya yasal sorunları düzeltmediği sürece, önizleme/sürüm adayı sürümünün yayımlanması hataya neden olan değişiklik sürümlerinden önce gider. Data API builder'ın önceki sürümleri GitHub sürümleri sayfasında kullanılabilir durumda kalabilir ancak hata düzeltmeleri içerebilecek en son sürüme yükseltmenizi öneririz.
Önizleme sürümleri
Veri API'sinin oluşturucu önizleme sürümleri, sürüm oluşturma düzeniyle X.Y.Z-rc tanımlanır. Sonek, -rc derlemenin bir "yayın adayı" olduğunu gösterir. Önizleme sürümleri, yeni özellikler ve diğer değişiklikler hakkında geri bildirim toplamak için kullanılır.
Son kararlı sürümden önemli değişiklikler yapmayı planlamadığımız sürece, en son kararlı sürüm ve yeni önizleme özellikleriyle birlikte bir sonraki önizleme sürümünü yayımlarız. Sonraki Veri API'si oluşturucusu güncelleştirmesi, önizleme sürümleri arasına eklediğimiz yeni önizleme özelliklerinden bazılarını bozabilir. Bu hataya neden olan davranış, işlerin yeniden çalışması için kodunuzu değiştirmeniz gerekebileceği anlamına gelir.
Önizleme sürümleri uzun süreli veya üretim amaçlı kullanım için tasarlanmamıştır. Yeni bir kararlı veya önizleme sürümü kullanıma sunulduğunda, eski önizleme sürümlerine artık erişilemiyor olabilir. Önizleme sürümlerini yalnızca yeni özellikler üzerinde etkin bir şekilde çalışırken ve yayından hemen sonra önizleme olmayan bir sürüme geçmeye hazır olduğunuzda kullanmak en iyisidir. Önizleme sürümündeki bazı özellikler yeni kararlı bir sürüme dahil edilirse, denemeniz için kalan önizleme özellikleri yeni bir önizleme sürümüne eklenir.
Sürüm değiştirme tablosu
Önemli
Değişiklik kritik ürün hatalarını, yasal, güvenlik veya gizlilik sorunlarını giderdiğinde küçük veya düzeltme eki yayınlarında hataya neden olan bir değişiklik gösterebiliriz.
| Sürüm türü | Önceki Sürüm | Yeni Sürüm | Notlar |
|---|---|---|---|
| Yeni Değişiklik | 1.Y.Z |
2.Y.Z |
Yeni özellikler ve hata düzeltmelerinin yanı sıra hataya neden olan değişiklikler. |
| Dengeli | 1.1.Z |
1.2.Z |
Değişiklikler kritik ürün hatalarına, yasal, güvenlik veya gizlilik sorunlarına çözüm bulmadığı sürece yeni özellikler ve hata düzeltmeleri hataya neden olmaz. |
| Dengeli | 1.1.1 |
1.1.2 |
Değişiklikler kritik ürün hatalarına, yasal, güvenlik veya gizlilik sorunlarına çözüm bulmadığı sürece yeni özellik içermeyen hata düzeltmeleri veya hataya neden olan değişiklikler. |
| Önizleme | X.Y.1-rc |
X.Y.2-rc |
Yeni önizleme özellikleri ve hata düzeltmeleri. (Ana sürümde hataya neden olan değişiklikler eklenir.) |
Hataya Neden Olan Değişiklikler
Güvenliği önceliklendirmek, özellikleri geliştirmek ve kod kalitesini korumak için yazılımlarımızın yeni sürümleri hataya neden olan değişiklikler içerebilir. Bu değişiklikleri dikkatli mimari seçimlerle en aza indirmeye çalışırken, yine de gerçekleşebilir. Bu gibi durumlarda bunları duyurmayı ve olası çözümleri sağlamayı öncelikli hale getiririz.
Önemli
Değişiklik hataya neden olmayan bir durum olarak kabul edilirse veya kritik ürün hatalarını ya da yasal, güvenlik veya gizlilik endişelerini gidermek için yapılan hataya neden olan bir değişiklikse, önceden bildirimde bulunmadan değişiklikler yapabiliriz.
Hataya neden olan değişiklik nedir?
Hataya neden olan değişiklik, kesintileri önlemek için uygulamanızı güncelleştirmenizi gerektiren bir değişikliktir. Veri API'si oluşturucusunda hataya neden olan değişiklikler REST API sözleşmelerinde, GraphQL şema oluşturmada ve uyumluluk ile işlevselliği etkileyen diğer öğelerde değişiklik içerebilir.
Hataya neden olan değişiklik örnekleri
Aşağıdaki örnekler, Veri API'si oluşturucusunun hataya neden olan değişikliklerinin bitmeyen bir listesidir:
- REST API sözleşme değişiklikleri
- GraphQL şema oluşturmada değişiklikler
- Geriye dönük uyumluluğu etkileyen değişiklikler
- API'leri veya parametreleri kaldırma veya yeniden adlandırma
- Hata kodlarındaki değişiklikler
- İzin tanımı işlevselliğinde yapılan ayarlamalar
- İzin verilen parametrelerin, istek alanlarının veya yanıt alanlarının kaldırılması
- Varsayılan değerler olmadan zorunlu parametrelerin veya istek alanlarının eklenmesi
- Hedeflenen API uç noktası işlevinde yapılan değişiklikler
Bölünemez değişikliğin tanımı
Hataya neden olmayan bir değişiklik, kesintiye neden olmadan uygulamanızla tümleştirilebilen bir değişikliği ifade eder. Bölünemez değişiklikler genellikle uygulamadan sonra iletilir. Uygulamanız önceden bildirimde bulunmaksızın bu değişiklikleri işleyecek şekilde tasarlanmalıdır.
HataYa Neden Olmayan Değişiklik Örnekleri
Aşağıdaki örnekler, Veri API'sinin oluşturucusunun bölünmez değişikliklerinin bitmeyen bir listesidir:
- Yeni uç noktalara giriş
- Mevcut uç noktalara yöntem ekleme
- Yanıtlarda ve isteklerde yeni alanların birleştirilmesi
- Yanıtlar içindeki alan düzeninde yapılan ayarlamalar
- İsteğe bağlı istek üst bilgilerine giriş
- Veri uzunluğu ve yanıt boyutu değişiklikleri
- Hata iletileri ve kodlarda yapılan değişiklikler
- HTTP yanıt kodlarına düzeltmeler
- Oluşturulan OpenAPI belgelerinde ek meta veriler
Hataya neden olan değişiklikleri nasıl ileteceğiz?
Hataya neden olan değişiklikler hakkında sizi bilgilendirmeyi öncelikli hale getiririz. Hataya neden olan değişiklik bildirimlerini GitHub'daki Data API builder sürümlerinin sürüm notlarında ve ayrılmış hataya neden olan değişiklikler listesi makalesinde bulabilirsiniz.
Geçerli hataya neden olan değişiklik listesi
Hataya neden olan değişiklikler ve özellik kullanımdan kaldırma işlemleri bu makalede duyurulur.
- Şu andan itibaren hataya neden olan bir değişiklik yoktur