PostgreSQL Yönetici Dokümantasyon Projesi Katkı Rehberi

PostgreSQL Dokümantasyon Projesi Katkı Rehberi

TÜBİTAK BİLGEM YTE olarak ülkemizde açık kaynak çalışmaları kapsamında uzun süredir hem kritik sistemlerde kullandığımız hem de ülkemizde yaygınlaşması için faaliyetlerde bulunduğumuz Açık Kaynak PostgreSQL Veritabanı Yönetim Sistemi için Türkçe dokümantasyonları açık kaynak olarak yayınlamaya başlıyoruz. PostgreSQL Yönetici Dokümantasyonu, hem yazılım geliştiriciler için, hem de üniversitelerdeki öğrenciler için planlı bir kaynak olması niyetiyle hazırlanmıştır. Açık Kaynak Topluluğundan beklentimiz, bu projemize katılmaları, bu dokümantasyonu geliştirmeleri, kullanmaları ve yaymalarıdır.

Projeyi Düzenleme

1. Projeyi düzenlemek için öncelikle repository’nin fork edilmesi gerekmektedir.

2. Repository fork edildikten sonra yapılmak istenilen katkılar aşağıda belirtildiği şekilde yapılır ve açıklayıcı bir commit mesajı ile commit edilir.

3. Commit edildikten sonra repository’e dönülür ve açıklayıcı bir mesaj ile pull request açılır.

4. Pull request açıldıktan sonra proje yöneticileri duruma göre katkıyı ekler veya geri çevirir.

Yeni Sayfa Ekleme

PostgreSQL dokümantasyon projesi sayfaları markdown formatında /pages/mydoc klasöründe bulunmaktadır. Yeni sayfa eklemek isteyen kullanıcılar öncelikle bu klasörde aşağıda belirtilen formatta bir dosya oluşturmalıdır.

Oluşturulan dosyanın isim formatı:

dosya_ismi.md      Örnek: mydoc_dosya_konumlari.md

Eklenecek Markdown dosyası ilgili sayfaya göre aşağıdaki formatta başlamalıdır.

---
title: "Dosya Konumları"
tags: [PostgreSQL]
keywords: postgres
last_updated: December 31, 2020
sidebar: mydoc_sidebar
permalink: mydoc_dosya_konumlari.html
folder: mydoc
---

• title, keywords, tags: İlgili sayfanın konusuna göre belirlenir.
• last_updated: dosyanın yaratıldığı tarih girilir.
• sidebar: mydoc_sidebar olmak zorundadır.
• permalink: Markdown dosyasının ismi (.md hariç) sonuna ‘.html’ konarak eklenir. Örnek:

dosya_konumlari.md ---> dosya_konumlari.html

• folder: mydoc olarak belirtilir.

Eklenecek sayfayı tanımlayan sayfa üst bilgisi bu şekilde eklendikten sonra içerik kısmı Markdown formatında yazılır.

Dosya yukarda belirtilen şekilde uluşturulup kaydedildikten sonra soldaki panele eklenmesi gerekmektedir. Bunun için _data\sidebars\mydoc_sidebar.yml dosyasına gidilir. Bu dosyanın özel bir formatı vardır ve bu formata uymak zorunludur. Eğer bir indentation hatası bulunursa konsolda hata mesajı verilir ve web sitesi çalışmayı durdurur. Her bir alt bölmeye geçildiğinde üsttekine göre bir boşluk bırakılır ve istenilen sayfa uygun başlık altına eklenir.

  - title: Veritabanı Yapılandırması
    output: web, pdf
    folderitems:

    - title: Parametreleri Ayarlama
      url: /mydoc_paremetreleri_ayarlama.html
      output: web, pdf

    - title: Dosya Konumları
      url: /mydoc_dosya_konumlari.html
      output: web, pdf

    - title: Bağlantılar ve Kimlik Doğrulama
      url: /mydoc_baglantilar_kimlik_dogrulama.html
      output: web, pdf

    - title: Kaynak Tüketimi
      url: /mydoc_kaynak_tuketimi.html
      output: web, pdf

    - title: Write Ahead Log
      url: /mydoc_wal.html
      output: web, pdf

    - title: Replication
      url: /mydoc_replication.html
      output: web, pdf

• title: Eklenen sayfanın yan panelde görüneceği başlık (title) belirlenir.
• URL: Markdown dosyasının ismi (.md hariç) sonuna .html uzantısı, başına / eklenerek yazılır.

mydoc_dosya_konumlari.md --> /mydoc_dosya_konumlari.html

• Output kısmına ise web, pdf yazılılarak dosyada uygun başlık altına eklenir.

- title: Veri Tipleri
  url: /veri_tipleri.html
  output: web, pdf

Mevcut Sayfaları Düzenleme

1. Düzenlemek istediğiniz sayfada Düzeltme Öner butonuna tıklanır.

2. Sayfa açıldıktan sonra sağ üstteki kalem ikonuna basılır.

3. Metin editörü açıldıktan sonra istenilen değişiklikler yapılır. Bu değişikliklerin önizlemesi üstte bulunan Preview Changes kısmında görülebilir. Değişiklikler yapıldıktan sonra açıklayıcı bir mesaj yazılır ve Propose Changes butonuna basılır.

4. Açılan sayfada Create Pull Request butonuna basılır.

5. Açılan pull request sayfasında Create Pull Request butonuna basılır ve değişiklikler proje yöneticisine gönderilir.

6. Yapılan değişiklikler proje yöneticisi tarafından incelenerek kabul edilir veya geri çevrilir.

Sayfa İçeriği Formatı

Uyarı Metni Türleri

• note.html
• tip.html
• warning.html
• important.html

Bu uyarı türleri farklı bir renk, simge ve uyarı kelimesine sahip olmaları dışında aynı işlevi görürler. Ekleyeceğiniz yazılarda istediğiniz şablonunu seçip kullanarak yazılarınızı daha renkli ve dikkat çekici hale getirebilirsiniz. Birden çok paragrafa ihtiyacınız varsa, <br/><br/> etiketleri girin.

{% include note.html content="Notunuzu buraya ekleyin." %}

{% include tip.html content="Buraya ipucunu ekle." %}

{% include important.html content="Önemli bilgilerinizi buraya ekleyin." %}

{% include warning.html content="Uyarınızı buraya ekleyin." %}

Bu şablonların çıktıları şu şekilde olacaktır:

Açıklama Metinleri

Her biri farklı açıklama metni türüne sahip şablonları ile ekleyeceğiniz yazıları daha renki ve dikkat çekici yapabilirsiniz.

{% include callout.html content="This is my **danger** type callout. It has a border on the left whose color you define by passing a type parameter." type="danger" %}

{% include callout.html content="This is my **default** type callout. It has a border on the left whose color you define by passing a type parameter." type="default" %}

{% include callout.html content="This is my **primary** type callout. It has a border on the left whose color you define by passing a type parameter." type="primary" %}

{% include callout.html content="This is my **success** type callout. It has a border on the left whose color you define by passing a type parameter." type="success" %}

{% include callout.html content="This is my **info** type callout. It has a border on the left whose color you define by passing a type parameter." type="info" %}

{% include callout.html content="This is my **warning** type callout. It has a border on the left whose color you define by passing a type parameter." type="warning" %}

Bu şablonların çıktıları şu şekilde olacaktır:

Parametre Bilgisi Ekleme

PostgreSQL Yönetici Dökümantasyon Projesin’de ‘Veritabanı Yapılandırması’ başlığı altında verilen parametrelerin bilgileri ( type, default, context, values, restart ) postgresqlco.nf‘den çekilmiştir. Version 13 parametre bilgileri projede _data/parameters.yml altında datafile olarak depolanmaktadır. Yeni eklenecek parametrelerin bilgilerine aşağıdaki yapı kullanılarak kolayca erişilebilir.

{% include parameter_info.html parametre="<parametre_ismi>" %}

Örneğin,

{% include parameter_info.html parametre="track_activity_query_size" %}

kullanımı yeni eklenen “track_activity_query_size” parametresi için size şu şekilde bir çıktı sağlar.

Resim Ekleme

Dokümantasyon projesinde yer alan sayfalara eklenecek resimler images/ klasörü altında toplanmaktadır. Yazdığınız yazılara ekleyeceğiniz resimleri uygun bir isimle bu klasöre ekledikten sonra aşağıdaki formatta kullanabilirsiniz.

{% include image.html file="contribution-postgresql.png" alt="PostgreSQL" caption="Bu bir örnek resim açıklaması" %}

Kod Örnekleri

```sql
CREATE TABLE measurement (
    city_id         int not null,
    logdate         date not null,
    peaktemp        int,
    unitsales       int
) PARTITION BY RANGE (logdate);
```

Sonuç:

CREATE TABLE measurement (
    city_id         int not null,
    logdate         date not null,
    peaktemp        int,
    unitsales       int
) PARTITION BY RANGE (logdate);

Desteklenen dillerin listesi için bkz

Bağlantılar

Dış bağlantı oluşmak için:

[PostgreSQL Server Administration](https://www.postgresql.org/docs/13/admin.html)

PostgreSQL Server Administration

Mevcut sayfalara bağlantı oluşturmak için:

[Sorguların İşlenmesi](mydoc_query_processing.html)

Sorguların İşlenmesi

Tablo Oluşturma

Eklenecek yazılarda tablo oluşturmak için Multimarkdown sözdizimini kullanabilirsiniz. Aşağıda bir örnek gösterilmektedir:

| Dosya | Tanım |
|-------|------|
| **PG_VERSION** | PostgreSQL'in majör sürüm numarasını içeren dosya |
| **pg_hba.conf** | PosgreSQL istemci kimlik doğrulaması kontrolü dosyası |
| **pg_ident.conf** | PostgreSQL user name mapping kontrol dosyası |
| **postgresql.conf** | PostgreSQL yapılandırma parametrelerini ayarlama dosyası |
| **postgresql.auto.conf** | ALTER SYSTEM ile ayarlanan yapılandırma parametrelerini depolamak için kullanılan dosya |
| **postmaster.opts** | Sunucunun en son başlatıldığı komut satırı seçeneklerini kaydeden dosya |

Yazı Vurgulama

*Bu yazı italik yazılır*

_Bu yazı da italik yazılır_

**Bu yazı kalın yazılır**

__Bu yazı da kalın yazılır__

`Vurgulu yazı`

**`Vurgulu yazı`**

Bu yazı italik yazılır

Bu yazı da italik yazılır

Bu yazı kalın yazılır

Bu yazı da kalın yazılır

Vurgulu yazı

Vurgulu yazı

Paragraflar

Markdown’da paragraf yaratmak için metinler arasında bir ya da daha fazla boş satır bırakın.

Örnek:
Markdown kullanması çok basit bir metin formatıdır.

Sanırım gelecekte yazacağım bütün dokümanlarda Markdown kullanacağım.

Başlıklar

# En büyük başlık (HTML'de <h1>)
## Biraz daha küçük (HTML'de <h2>)
###### En küçük başlık (HTML'de <h6>)

Çıktı şu şekilde gözükecek:
# En büyük başlık
## Biraz daha küçük
###### En küçük başlık

Listeler

Sırasız

* Dosya 1
* Dosya 2
  * Dosya 2a
  * Dosya 2b

Çıktı şu şekilde gözükecek:

• Dosya 1
• Dosya 2
  • Dosya 2a
  • Dosya 2b

Sıralı

1. Dosya 1
2. Dosya 2
3. Dosya 3
   1. Dosya 3a
   2. Dosya 3b

Çıktı şu şekilde gözükecek:

1. Dosya 1
2. Dosya 2
3. Dosya 3
   1. Dosya 3a
   2. Dosya 3b

Alıntılar

Örnek:
Atatürk'ün dediği gibi:

> Hayatı ve özgürlüğü için ölümü 
>
> göze alan bir millet asla yenilmez.

Çıktı şu şekilde gözükecek:

Atatürk’ün dediği gibi:

Hayatı ve özgürlüğü için ölümü

göze alan bir millet asla yenilmez.