Uzantınız için kullanıcı dokümanları oluşturun

Her uzantının, kullanıcılara uzantının ne işe yaradığını ve nasıl kullanılacağını öğreten dokümanları olmalıdır.

Gerekli minimum dokümanlar, aşağıdaki üç Markdown dosyasından oluşur:

• PREINSTALL.md
• POSTINSTALL.md
• CHANGELOG.md

Ayrıca şunları da üretebilirsiniz:

• Uzantının herkese açık deposu için bir README dosyası.
• Kendi web sitenizde yayınlanan ve PREINSTALL.md'ünüze bağlı uzun eğitici içerikler, kılavuzlar ve referanslar

En iyi uygulamalar, yaygın ifade ve yapıları öğrenmek için resmi Firebase uzantılarıyla kullanılabilen dosyaları incelemenizi öneririz.

README dosyası oluşturma

Uzantı dizininizde isteğe bağlı olarak bir README dosyası bulunabilir. firebase ext:dev:init komutunun sizin için otomatik olarak bir tane oluşturmadığını unutmayın.

Bununla birlikte, Firebase CLI, extension.yaml dosyanızdan ve PREINSTALL.md dosyanızdan alınan içeriği içeren bir README dosyasını otomatik olarak oluşturmak için aşağıdaki kolaylık komutunu destekler:

firebase ext:info ./path/to/extension --markdown > README.md

Resmi Firebase uzantılarının tüm README dosyaları bu komut kullanılarak oluşturulur.

Kurulum bilgileri ekleme

README dosyasını yazdıktan veya oluşturduktan sonra yükleme bilgilerini ekleyin. Şablon olarak aşağıdaki snippet'i kullanabilirsiniz:

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

PREINSTALL dosyası yazma

PREINSTALL dosyası, uzantınıza genel bakış sunan bir tür "pazarlama" sayfasıdır.

Bu dosyada ne tür bir içerik var?

• Uzantı işlevinizin kapsamlı açıklaması
• Veritabanı kurulumu veya Google dışı bir hizmete erişim gibi ön koşulların listesi (örnek)
• Kurulum öncesi görevlerin ve talimatlarının kısa açıklaması
• Yükleme sonrası görevlerin kısa açıklaması (örnek) (ayrıntılı talimatlar POSTINSTALL bölümüne eklenir)
• Faturalandırmayla ilgili sonuçların kısa açıklaması (standart metin ile başlayın)

Bu içerik kullanıcıya nerede gösteriliyor?

Firebase konsolu">

Firebase Konsolu">

• extensions.dev adresindeki uzantının sayfasında.
• Uzantınıza ait kaynak kod deponuz (uzantı dizininde)
• Uzantının README dosyasında (Firebase CLI --markdown > README.md işaretini kullanıyorsanız)

PREINSTALL dosyaları, uzantının parametre değerlerine erişemez. Bu nedenle, parametre referanslarının gerçek değerlerle oluşturulmasını bekleyemezsiniz.

En iyi uygulamalardan bazıları nelerdir?

• Mümkünse PREINSTALL dosyasının tüm içeriğini bir sayfanın altında tutun
• Nihai kullanıcının uzantıyı yüklemeden önce kesinlikle bilmesi gereken ayrıntı düzeyini sağlayın
• Ayrıntılı talimatları POSTINSTALL dosyasına veya diğer ek dosyalara ekleyin
• Uzantı için başka araçlar veya komut dosyaları sağlayıp sağlamadığınızı kısaca belirtin

Billing

This extension uses other Firebase or Google Cloud services which may have
  associated charges:

*   <list Google services / products that your extension uses>
*   <list Firebase services that your extension uses>
*   Cloud Secret Manager <if the extension uses secret params>
*   Cloud Functions

When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)

<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.

POSTINSTALL dosyası yazma

POSTINSTALL dosyası, uzantınızın ayrıntılı kurulum sonrası talimat sayfasıdır.

Bu dosyada ne tür bir içerik var?

• Firebase güvenlik kurallarını ayarlama veya istemci tarafı kod ekleme gibi zorunlu kurulum sonrası görevler için ayrıntılı talimatlar (örnek)
• Yüklenen uzantıyı hemen denemeye yönelik genel talimatlar (örneğin, "Konsola gidin ve bunu yapın")
• Özellikle HTTP isteğiyle tetiklenen uzantılar için uzantının nasıl tetikleneceğiyle ilgili temel bilgiler
• Yüklenen uzantının nasıl izleneceğine dair kısa talimatlar (standart metin ile başlayın)

Bu içerik kullanıcıya nerede gösteriliyor?

Firebase konsolu">

Firebase Konsolu">

• Bir kullanıcı uzantınızı yükledikten sonra Firebase konsolunda (yüklü uzantının ayrıntı kartında)

  • Uzantılarınızı gerçek bir projeye yükleyerek POSTINSTALL içeriğinin görüntülenmesini inceleyin.

• Uzantınıza ait kaynak kod deponuz (uzantı dizininde)

POSTINSTALL dosyaları, uzantı için parametre değerlerine ve işlevle ilgili çeşitli değişkenlere erişebilir. POSTINSTALL içeriği Firebase konsolunda görüntülendiğinde parametre veya değişken referansları yerine gerçek değerler gösterilir. POSTINSTALL dosyanızda parametrelere ve değişkenlere referans verme hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

En iyi uygulamalardan bazıları nelerdir?

• POSTINSTALL dosyasının tüm içeriği kısa ve öz ancak açıklayıcı olmalıdır.
• Farklı görevleri veya kavramları ayırmak için başlıkları kullanarak içeriği bölümlere ayırın.
• Belirli bir iş akışı veya görevle ilgili ayrıntılı talimatları web sitenizde (örnek) ya da uzantı deposundaki ek Markdown dosyalarında (örnek) yayınlayabilirsiniz.
• Kullanıcının yapılandırılmış değerleri talimatlar bağlamında görebilmesi için parametrelere ve işlevle ilgili değişkenlere referans verin.

Parametrelere ve değişkenlere referans verme

Yükleme işleminden sonra Firebase konsolu, uzantının POSTINSTALL dosyasının içeriğini gösterir. POSTINSTALL dosyanızda parametrelere ve işlevle ilgili değişkenlere (aşağıdaki tabloya bakın) referans verirseniz konsol bu referansları, yüklü örneğin gerçek değerleriyle doldurur.

Aşağıdaki söz dizimini kullanarak POSTINSTALL dosyasında yapılandırılmış parametre değerlerine erişin: ${param:PARAMETER_NAME}

Aşağıdaki işlevle ilgili değişkenlere yalnızca POSTINSTALL dosyanızda de referans verebilirsiniz. Firebase, yükleme sonrası kullanıcılarınıza daha kolay yol gösterebilmeniz için bu değişkenleri destekler. Bu değişkenlerin değerleri yükleme işleminden sonra kullanılabildiği için yalnızca POSTINSTALL dosyasında kullanılabilirler.

Bu tabloda function-name, işlevin extension.yaml içindeki kaynak nesnesinde bulunan name alanının değeridir.

Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.

Uzantıların nasıl tetikleneceğini belgeleme

Uzantı kullanıcı dokümanlarınızda, kullanıcılarınıza uzantınızı nasıl tetikleyecekleri konusunda talimat vermeniz gerekir. Bu talimatlar, gerekli olduğunu düşündüğünüz kadar ayrıntılı olabilir ancak POSTINSTALL dosyası yazmayla ilgili en iyi uygulamaları göz önünde bulundurun. Bu talimatları nasıl sağlayacağınızla ilgili yardım için aşağıdaki, uzantınızla ilgili bölümü genişletin.

CHANGELOG dosyası yazma

Bu dosyada ne tür bir içerik var?

Her uzantının, yayınladığınız uzantınızın her yeni sürümünde yer alan değişiklikleri belgeleyen bir CHANGELOG.md dosyası olmalıdır. Her sürümü 2. düzey bir başlığın (##) altına koyun. Dilerseniz istediğiniz Markdown biçimlendirmesini kullanabilirsiniz.

Aşağıdaki örnek, resmi uzantılardan birinden alınmıştır:

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

Bu içerik kullanıcıya nerede gösteriliyor?

• Firebase konsolunda ve CLI'de, kullanıcılar uzantınızın yeni sürümlerine yükselttiğinde. Firebase Konsolu ve CLI, yalnızca kullanıcı yükseltmeyi tamamlarsa geçerli olacak değişiklikleri gösterir.
• Uzantınızın kaynak kodu deposu (uzantı dizininde).