Teknik Bir Makaledeki Kullanımdan Kaldırılan (Deprecated) Bir API'nin Hâlâ Çalışıp Çalışmadığı Nasıl Kontrol Edilir?
Teknik bir makale kullanımdan kaldırılmış bir API'ye atıfta bulunduğunda, ilgili sembolü projenin sürümlendirilmiş belgeleri, sürüm notları ve geçiş talimatları üzerinden tam olarak takip edin. “Kullanımdan kaldırıldı” (deprecated), geliştiricilerin bir API'yi değiştirilmek veya gelecekte kaldırılmak üzere işaretlediği anlamına gelir; tek başına bu durum, API'nin halihazırda tamamen kaldırıldığı anlamına gelmez. Uyarının ilk kez hangi sürümde ortaya çıktığını teyit edin, ardından API'nin kaldırıldığını ve belgelenen alternatifini görmek için daha sonraki sürüm notlarını kontrol edin. Django'nun `django.conf.urls.url()` fonksiyonu net bir örnek sunar: Django 3.1, bunu `django.urls.re_path()` lehine kullanımdan kaldırmış ve Django 4.0 ise tamamen kaldırmıştır.
Kesin API ve sürümle başlayın
Kütüphaneyi, tam içe aktarma yolunu (import path) veya metot adını ve makalenin hedeflediği sürümü kaydedin. Yalnızca bir ad yanıltıcı olabilir: paketler benzer adlara sahip API'ler sunabilir ve mevcut belgeler daha yeni bir sürümü anlatırken makale eski bir sürüme atıfta bulunuyor olabilir. Gerçek sembolü tanımlamak için kod örneğinin içe aktarmalarını (imports) ve çevreleyen bağlamı kontrol edin.
Ardından, makalede belirtilen sürüme ait resmi belgeleri bulun. “Kullanımdan kaldırıldı” (deprecated), “kaldırıldı” (removed) veya “geriye dönük uyumsuz” (backwards incompatible) gibi durum etiketlerini arayın. Daha sonra bunu, bir okuyucunun kullanacağı sürüme ait belgelerle karşılaştırın. Güncel bir belge sayfası eski bir API'yi tamamen atlayabilir; bu nedenle orada yer almaması araştırmayı gerektiren bir ipucudur, ne zaman veya neden kaybolduğunun bir kanıtı değildir.
Zaman çizelgesini oluşturmak için sürüm notlarını kullanın
Sürüm notları, bir değişikliği belirli bir sürüme bağlar. [Django 3.1 sürüm notlarında](https://docs.djangoproject.com/en/3.1/releases/3.1/), geliştiriciler `django.conf.urls.url()` fonksiyonunu kullanımdan kaldırılmış olarak listeler ve alternatifi olarak `django.urls.re_path()` fonksiyonunu belirtir. [Django 4.0 sürüm notlarında](https://docs.djangoproject.com/en/4.0/releases/4.0/) ise aynı API, kullanımdan kaldırılma döngüsünü tamamladıktan sonra kaldırılan özellikler altında yer alır. Bu iki kayıt bir sıra belirler: 3.1'de kullanımdan kaldırıldı, 4.0'da tamamen kaldırıldı.
Proje açıkça belirtmediği sürece, bir kullanımdan kaldırma bildiriminden bir yayınlanma tarihi veya nihai kaldırılma tarihi çıkarmayın. Projeler, kullanımdan kaldırılan arayüzleri ne kadar süreyle korudukları konusunda farklılık gösterir ve bazıları uyumluluğu uzun süre devam ettirir. Bir sürüm notu bir API'nin kaldırıldığını söylediğinde, bu maddenin tüm API için mi geçerli olduğunu yoksa istisnalar mı belirttiğini doğrulayın. Örneğin Django 4.0, geçmiş migrasyonlardaki destek hariç olmak üzere `NullBooleanField`ın kaldırıldığını belirtir. Bu istisna, eski migrasyon dosyalarıyla çalışan geliştiriciler için önemlidir.
Kodu değiştirmeden önce geçiş kılavuzunu kontrol edin
Yeni bir alternatif benzer görünebilir ancak farklı davranışlara veya gereksinimlere sahip olabilir. Sürüm notlarından bağlantı verilen geçiş sayfasını takip edin, ardından alternatifin sürümlendirilmiş referansını inceleyin. Django'nun [sürüm yükseltme kılavuzu](https://docs.djangoproject.com/en/4.0/howto/upgrade-version/), yükseltmeye devam etmeden önce mevcut sürümdeki kullanımdan kaldırma uyarılarının çözülmesini önerir. Bu tavsiye, belirsiz bir belge kontrolünü pratik bir sıraya dönüştürür: desteklenen adımlar dahilinde yükseltin, uyarıları ortaya çıkarın, projenin kendi kullanımlarını düzeltin ve ancak o zaman kaldırma işleminin geçerli olduğu sürüme geçin.
Django URL örneğinde belgelenen alternatif `re_path()` fonksiyonudur. İçe aktarma yolunu ve davranışı hedef sürümün belgelerine göre doğrulayın. Bu geçmiş sürümler değişikliği örneklemektedir; bunları bugün yüklemeniz için bir öneri değildir.
Kullanımdan kaldırılan, kaldırılan ve kullanılabilir olanı ayırt edin
Durumu ifade ederken kesin bir dil kullanın:
Bir örneğin bir ortamda çalışıyor olması nedeniyle mevcut bir bakım desteğinin sürdüğünü varsaymayın. API'nin tam olarak hedeflenen sürümün belgelerinde kullanılabilir olarak yer aldığını doğrulayın ve sonraki sürümlerdeki kullanımdan kaldırma bildirimlerini kontrol edin. Eski bir sürümde kullanılabilir olması, o sürümün hâlâ bakım gördüğü anlamına gelmez.
Python'un standart kütüphanesi sürüm numaralarının neden önemli olduğunu açıkça göstermektedir. [Python 3.9 “Yenilikler” (What's New) notları](https://docs.python.org/3/whatsnew/3.9.html), `collections.Mapping` gibi takma adların Python 3.3'ten beri bir `DeprecationWarning` verdiğini ve Python 3.9'un bu geriye dönük uyumluluk takma adlarını sağlayan son sürüm olduğunu belirtir. Aynı notlar, kullanımdan kaldırmaları ortaya çıkarmak için uyarı seçenekleriyle test yapılmasını tavsiye eder. `collections.Mapping`i Python sürümünü belirtmeden yalnızca “kullanımdan kaldırıldı” olarak etiketleyen bir makale, okuyucuların bir uyarıyla mı yoksa eksik bir öznitelikle mi karşı karşıya olduğunu anlamalarını imkansız kılar. Belgelenen `collections.abc` konumunu tercih edin ve durumu için hedeflenen Python sürüm notlarını kontrol edin.
Takipten editoryal bir karar çıkarın
İnceleme zincirini tamamladıktan sonra makale için bir aksiyon belirleyin. Örnek, belirtilen ortamda kullanılabilir olarak belgelenmişse sürümü ve durumu doğru şekilde etiketleyin. Kullanımdan kaldırılmış ancak hâlâ kullanılabilir durumdaysa bunu açıkça belirtin, alternatifini gösterin ve okuyucuların hangi sürüm için plan yapması gerektiğini açıklayın. Tamamen kaldırılmışsa kodu güncelleyin ve artık kullanılamadığı ilk sürümün adını verin; tarihsel bir notu yalnızca okuyucuların daha eski projeleri anlaması gerektiğinde saklayın.
Kısa ve öz bir kanıt notu, gelecekteki belirsizlikleri önlemeye yardımcı olur: API'nin tam adını, ilk kullanımdan kaldırma sürümünü, varsa kaldırılma sürümünü, alternatifini ve resmi kayıtların URL'lerini kaydedin. Resmi kaynaklar bir kaldırma sürümü veya alternatif belirtmiyorsa, kopyalanmış bir kod parçası veya doğrulanmamış bir makaleyle bu boşluğu doldurmak yerine durumun belirsiz olduğunu ifade edin. Sonuç olarak ortaya, bir API'nin “eski” olduğuna dair zamansız bir iddia yerine, okuyucuların harekete geçebileceği sürüme özgü bir düzeltme çıkar.