Changelog ve Readme.txt: WordPress Eklenti Dokümantasyonu Nasıl Yazılır?

Yazar:komut.io ekibi WordPress Eklentisi Geliştirme ve Yönetimi
0 Yorum

Bir WordPress eklentisi geliştiriyorsunuz, kodlar çalışıyor, özellikler tamamlandı. Ama projeyi GitHub’a ya da WordPress.org’a göndermeden önce iki dosya sizi bekliyor: readme.txt ve changelog. Bu iki dosyayı “şeklen doldurayım, geçeyim” diye ele alanların sonradan nasıl pişman olduğunu defalarca gördüm. Hem kendi projelerimde hem de müşteri eklentilerini incelediğimde, bu dosyaların ne kadar kritik olduğu ortaya çıkıyor. Dokümantasyon, eklentinin kullanıcıyla, WordPress ekosistemiyle ve ilerideki kendinizle kurduğu iletişimdir.

readme.txt Neden Bu Kadar Önemli

WordPress.org plugin repository’si, eklentinizi değerlendirirken readme.txt dosyasını adeta bir pasaport gibi kullanır. Yanlış format, eksik alan veya hatalı sözdizimi; eklentinizin reddedilmesine ya da yanlış kategorilerde listelenmesine neden olabilir. Ama bunun ötesinde, iyi yazılmış bir readme.txt hem arama motorlarında hem de WordPress admin panelindeki eklenti arama sonuçlarında sizi öne çıkarır.

WordPress.org, readme.txt içindeki bilgileri ayrıştırarak eklenti sayfasını otomatik oluşturur. Açıklama metniniz, ekran görüntüleriniz, SSS bölümünüz ve changelog’unuz doğrudan bu dosyadan beslenir. Yani aslında tek bir kaynak dosyayla hem depo sayfanızı hem de admin içi görünümünüzü yönetiyorsunuz.

Temel readme.txt Yapısı

WordPress.org’un beklediği standart format şöyledir:

=== Eklenti Adı ===
Contributors: kullaniciadi
Tags: woocommerce, payment, invoice
Requires at least: 5.8
Tested up to: 6.4
Requires PHP: 7.4
Stable tag: 2.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Kısa açıklama buraya gelir. 150 karakteri geçmemeli.

== Description ==

Uzun açıklama buraya. Markdown benzeri sözdizimi desteklenir.

== Installation ==

1. Eklentiyi yükleyin
2. Aktive edin
3. Ayarları yapılandırın

== Frequently Asked Questions ==

= WooCommerce olmadan çalışır mı? =

Hayır, WooCommerce 6.0 ve üzeri gereklidir.

== Screenshots ==

1. Ana ayarlar ekranı
2. Ödeme entegrasyon paneli

== Changelog ==

= 2.1.0 =
* Yeni: Toplu fatura oluşturma özelliği eklendi
* Düzeltme: PHP 8.2 uyarıları giderildi

== Upgrade Notice ==

= 2.1.0 =
PHP 8.2 kullanıcıları için kritik düzeltmeler içerir.

Header alanlarındaki her satır ayrıştırıcı tarafından okunur. Requires at least ve Tested up to değerleri WordPress güncelleme sistemini etkiler. Kullanıcılar eski bir WordPress sürümündeyse eklentinizi “test edilmemiş” olarak görecekler, bu da yükleme oranlarını direkt olarak düşürür.

Tags Seçimi Stratejisi

Tags alanına rastgele kelime doldurmak yerine, WordPress.org’un onaylı etiket listesine bakın. Maksimum 5 etiket kullanabilirsiniz ve bunlar eklentinizin doğru kategorilerde görünmesini sağlar.

# Kötü örnek - genel ve etkisiz
Tags: wordpress, plugin, good, useful, free

# İyi örnek - spesifik ve aranabilir
Tags: woocommerce, invoicing, pdf, e-invoice, billing

Changelog Yazımının Sanatı

Changelog, versiyonlar arası değişikliklerin kaydıdır. “Bazı düzeltmeler yapıldı” gibi muğlak notlar ne kullanıcıya ne de kendinize fayda sağlar. İyi bir changelog, bir kullanıcının “bunu güncellemeli miyim?” sorusunu beş saniyede yanıtlamalıdır.

Anlamlı Changelog Kategorileri

Endüstride yaygın olarak kullanılan ve ben de tüm projelerimde standart haline getirdiğim kategoriler şunlardır:

  • Yeni (Added): Yeni özellikler, yeni hook’lar, yeni ayarlar
  • Değişti (Changed): Mevcut davranışta değişiklik, ama geriye dönük uyumlu
  • Düzeltildi (Fixed): Hata düzeltmeleri
  • Kaldırıldı (Deprecated): Yakında silinecek özellikler için uyarı
  • Silindi (Removed): Artık var olmayan özellikler
  • Güvenlik (Security): Güvenlik açıklarının kapatılması
== Changelog ==

= 2.1.0 - 2024-01-15 =
* Yeni: Toplu PDF fatura indirme özelliği (50 adede kadar)
* Yeni: REST API endpoint'i eklendi - /wp-json/my-plugin/v1/invoices
* Değişti: Fatura numaralandırma formatı {YIL}-{SIRA} şekline getirildi
* Düzeltildi: Çoklu para birimi kullanımında vergi hesaplama hatası
* Düzeltildi: PHP 8.2'de deprecated uyarısı veren str_replace kullanımı
* Güvenlik: Dosya yükleme endpoint'inde eksik nonce kontrolü eklendi

= 2.0.3 - 2023-12-02 =
* Düzeltildi: WooCommerce 8.3 uyumluluğu sağlandı
* Düzeltildi: Türkçe karakter içeren ürün adlarında PDF oluşturma sorunu

= 2.0.2 - 2023-11-10 =
* Düzeltildi: Depo dışı lisans doğrulama sonsuz döngüsü

Tarihleri eklemeyi ihmal etmeyin. Üç ay sonra bir müşteri “bu sürüm ne zaman çıktı?” diye sorduğunda CVS geçmişini karıştırmak yerine changelog’a bakıyorsunuz.

Upgrade Notice Bölümü

== Upgrade Notice == bölümü genellikle atlanır, ama kullanıcı deneyimi açısından son derece kritiktir. WordPress bu notu, eklenti güncelleme sayfasında küçük bir uyarı olarak gösterir.

== Upgrade Notice ==

= 2.0.0 =
UYARI: Bu büyük sürüm veritabanı şemasını değiştiriyor. Güncellemeden önce
yedek alın. Eski ayarlar otomatik migrate edilecek, ama ihtiyati olarak
yedek almanızı öneririz.

= 2.1.0 =
PHP 8.2 ve WooCommerce 8.3 kullanıcıları için önerilen güncelleme.

CHANGELOG.md ile readme.txt Farkı

WordPress projelerinde iki farklı changelog dosyası formatı vardır. Bunları birbirine karıştırmak ya da birini diğerinin kopyası yapmak yaygın bir hata.

readme.txt içindeki changelog, WordPress.org kullanıcılarına yönelik, sade ve anlaşılır bir dille yazılmalıdır. Teknik detaylardan ziyade kullanıcıyı etkileyen değişikliklere odaklanılır.

CHANGELOG.md ise geliştiricilere yönelik, GitHub veya GitLab gibi platformlarda görüntülenen, çok daha teknik bir belgedir. [Keep a Changelog](https://keepachangelog.com) standardını burada kullanabilirsiniz.

# CHANGELOG.md (Geliştirici odaklı)

## [2.1.0] - 2024-01-15

### Added
- `MyPlugin_Invoice::bulk_generate()` metodu eklendi
- REST API: `GET /wp-json/my-plugin/v1/invoices` endpoint'i
- `my_plugin_before_invoice_generate` action hook'u
- `my_plugin_invoice_number_format` filter hook'u

### Changed
- `MyPlugin_Invoice::get_number()` artık `{YIL}-{SIRA}` formatı döndürüyor
- Minimum PHP sürümü 7.4'ten 8.0'a yükseltildi

### Fixed
- Multi-currency senaryolarında `calculate_tax()` round hatası (#147)
- PHP 8.2 `str_replace()` deprecated kullanımı (`MPDF_TEMP_PATH`)

### Security
- `/upload-invoice` endpoint'inde nonce doğrulama eksikliği (CVSS 4.3)

Bu iki dosyayı eş zamanlı tutmak için bir otomasyon kurabilirsiniz. Aşağıdaki bash script, CHANGELOG.md dosyasındaki son versiyonu ayrıştırıp readme.txt formatına dönüştürmek için bir başlangıç noktası sunar:

#!/bin/bash
# changelog-sync.sh
# CHANGELOG.md'den readme.txt changelog bölümünü günceller

VERSION=$(grep -m1 "^## [" CHANGELOG.md | sed 's/## [(.*)].*/1/')
DATE=$(grep -m1 "^## [" CHANGELOG.md | sed 's/.*] - //')

echo "= $VERSION - $DATE ="

# Added bölümü
grep -A100 "^### Added" CHANGELOG.md | 
  grep -B100 "^###" | 
  grep "^- " | 
  sed 's/^- /* Yeni: /'

# Fixed bölümü  
grep -A100 "^### Fixed" CHANGELOG.md | 
  grep -B100 "^###" | 
  grep "^- " | 
  sed 's/^- /* Düzeltildi: /'

# Security bölümü
grep -A100 "^### Security" CHANGELOG.md | 
  grep -B100 "^###" | 
  grep "^- " | 
  sed 's/^- /* Güvenlik: /'

Versiyon Numaralandırma Tutarlılığı

readme.txt içindeki Stable tag değeri, eklentinin ana PHP dosyasındaki Version: header’ı ve CHANGELOG’daki son versiyon birbirini tutmalıdır. Bu üçünün senkronize olmaması, güncelleme bildirimlerinin çalışmamasına veya yanlış çalışmasına neden olur.

# my-plugin.php (plugin header)
/**
 * Plugin Name: My Awesome Plugin
 * Version: 2.1.0
 * ...
 */
define('MY_PLUGIN_VERSION', '2.1.0');

# readme.txt
Stable tag: 2.1.0

# Bu üçü her zaman aynı olmalı!

Bunu elle takip etmek hata yaratır. Bir bump-version.sh scripti ile version güncellemeyi otomatize etmek hem hızlandırır hem de tutarsızlıkları engeller:

#!/bin/bash
# bump-version.sh <yeni_versiyon>
# Kullanım: ./bump-version.sh 2.2.0

NEW_VERSION=$1

if [ -z "$NEW_VERSION" ]; then
    echo "Kullanım: $0 <versiyon>"
    exit 1
fi

# Plugin PHP dosyasını güncelle
sed -i "s/Version: .*/Version: $NEW_VERSION/" my-plugin.php
sed -i "s/define('MY_PLUGIN_VERSION', '.*')/define('MY_PLUGIN_VERSION', '$NEW_VERSION')/" my-plugin.php

# readme.txt güncelle
sed -i "s/Stable tag: .*/Stable tag: $NEW_VERSION/" readme.txt

echo "Versiyon $NEW_VERSION olarak güncellendi."
echo "Şimdi CHANGELOG.md ve readme.txt changelog bölümünü manuel güncelleyin."
git diff --stat

Gerçek Dünya Senaryo: Müşteri Eklentisinde Changelog Kaosu

Geçen yıl bir e-ticaret firmasının özel WooCommerce eklentisini devraldım. Önceki geliştirici iki yıl boyunca hiç changelog tutmamış. Eklentinin farklı sunucularda dört farklı versiyonu çalışıyordu ve hiçbirinde readme.txt yoktu.

Hangisinin güncel olduğunu bulmak için şu yaklaşımı kullandım:

# Her sunucudaki eklenti versiyonunu kontrol et
wp plugin get my-custom-plugin --field=version --allow-root
# ya da direkt PHP header'ından oku:
grep "Version:" wp-content/plugins/my-custom-plugin/my-custom-plugin.php

# Git log ile ne zaman ne değiştiğini anlamaya çalış
git log --oneline --all -- wp-content/plugins/my-custom-plugin/
git log -p --follow -- wp-content/plugins/my-custom-plugin/includes/class-main.php | head -100

Changelog olmadan, iki yıllık değişiklikleri commit mesajlarından ve git diff çıktılarından yeniden oluşturmak neredeyse tam bir iş günü sürdü. O günden sonra devralınan her projede ilk kontrolüm changelog’un varlığı ve kalitesidir.

Otomatik readme.txt Doğrulama

WordPress.org, readme dosyalarını parse etmek için kendi validator’ını sunuyor. Ama CI/CD sürecinize dahil edebileceğiniz basit bir lokal kontrol scripti şöyle yazılabilir:

#!/bin/bash
# validate-readme.sh

REQUIRED_FIELDS=("Requires at least" "Tested up to" "Stable tag" "License")
ERRORS=0

for field in "${REQUIRED_FIELDS[@]}"; do
    if ! grep -q "^$field:" readme.txt; then
        echo "HATA: '$field' alanı readme.txt içinde bulunamadı"
        ERRORS=$((ERRORS + 1))
    fi
done

# Stable tag ve plugin version uyumunu kontrol et
README_VERSION=$(grep "Stable tag:" readme.txt | awk '{print $3}')
PLUGIN_VERSION=$(grep "Version:" my-plugin.php | head -1 | awk '{print $3}')

if [ "$README_VERSION" != "$PLUGIN_VERSION" ]; then
    echo "HATA: readme.txt Stable tag ($README_VERSION) plugin versiyonuyla ($PLUGIN_VERSION) eşleşmiyor"
    ERRORS=$((ERRORS + 1))
fi

# Short description uzunluğunu kontrol et
SHORT_DESC_LENGTH=$(awk '/^$/{if(found) exit} /^== Description ==/{found=1}' readme.txt | head -1 | wc -c)

if [ $ERRORS -eq 0 ]; then
    echo "readme.txt doğrulama başarılı."
else
    echo "$ERRORS hata bulundu."
    exit 1
fi

Bu script’i .git/hooks/pre-commit veya GitHub Actions workflow’unuza ekleyerek her release öncesi otomatik çalıştırabilirsiniz.

Dil ve Ton Konusunda Pratik Notlar

Türkiye’deki birçok WordPress geliştiricisi readme.txt’i İngilizce yazıyor çünkü WordPress.org uluslararası bir platform. Bu doğru bir yaklaşım. Ama şunu da göz önünde bulundurun: Eğer eklentiniz yalnızca Türk kullanıcılara yönelikse (Türk e-fatura sistemi entegrasyonu, KVKK uyum araçları gibi), readme.txt içine Türkçe açıklama eklemek ve Description bölümünde Türkçe içerik bulundurmak yerel arama sonuçlarını iyileştirebilir.

Changelog dili için pratik önerim şudur: Kullanıcıya bakan notlar sade ve anlaşılır Türkçe, geliştiriciye bakan CHANGELOG.md ise İngilizce olsun. Bu şekilde hem local kullanıcı kitlesine hitap eder hem de ileride projeye katılacak uluslararası geliştiricilere teknik belgeyi erişilebilir kılarsınız.

Changelog yazarken özellikle kaçınmanız gereken ifadeler şunlardır:

  • “Çeşitli iyileştirmeler yapıldı” – Neyin iyileştirildiğini yazın
  • “Performans artırıldı” – Hangi operasyonda, ne kadar? Benchmark varsa ekleyin
  • “Küçük düzeltmeler” – Küçük bile olsa düzeltilen hatayı tanımlayın
  • “Güncelleme” – Bu hiçbir şey söylemiyor

Sonuç

readme.txt ve CHANGELOG.md, eklenti geliştirme sürecinin en çok ertelenen ama en az hak ettiği şekilde ihmal edilen parçalarıdır. Kod mükemmel çalışıyor olabilir, ama belgelenmemiş bir eklenti; hem kullanıcı güvenini zedeler hem de siz dahil gelecekteki geliştiricilerin işini gereksiz yere zorlaştırır.

Şu üç alışkanlığı edinin: Her commit’te değil ama her özellik tamamlandığında changelog’u güncelleyin, versiyon numaralarını üç ayrı yerde manuel yazmak yerine script ile güncelleyin ve Upgrade Notice bölümünü asla boş bırakmayın. Bu üç adımı rutininize kattığınızda, release süreçleri yarı yarıya kısalacak ve “bu sürümde ne değişmişti?” sorusu artık sizi yoracak bir soruya dönüşmeyecektir.

Belgeleme sıkıcı görünür, ama altı ay sonra gece yarısı bir production sorunu çözerken, o temiz changelog’a bakıp değişikliği iki saniyede tespit ettiğinizde, geçmişte vakit ayıran kendinize teşekkür edeceksiniz.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir