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 bir dokümanı olmalıdır.

Gerekli olan minimum dokümanlar şu üç Markdown dosyasından oluşur:

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

Ayrıca, aşağıdaki içerikleri de üretmeyi düşünebilirsiniz:

• Uzantının herkese açık deposu için bir README dosyası.
• Kendi web sitenizde yayınlanan ve PREINSTALL.md bölümünde bağlantısı verilen daha uzun biçimli eğitimler, kılavuzlar ve referanslar.

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

README dosyası oluşturma

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

Ancak Firebase CLI, extension.yaml dosyanızdan ve PREINSTALL.md dosyanızdan çekilen içerikleri 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 için tüm README dosyaları bu komut kullanılarak oluşturulur.

Kurulum bilgileri ekleme

Bir README dosyası yazdıktan veya oluşturduktan sonra, bu dosyaya 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ızın genel bakışıdır ve bir tür "pazarlama" sayfasıdır.

Bu dosyada hangi içerik var?

• Uzantınızın işlevinin 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 girilir)
• Faturalandırmayla ilgili etkilerin kısa açıklaması (standart metinle başlayın)

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

Firebase konsolu">

Firebase konsolu">

• extensions.dev adresindeki uzantı sayfasında.
• Uzantınızın kaynak kodu deposu (uzantı dizininin içinde)
• Uzantının README dosyasının bir parçası olarak (Firebase CLI'yı kullanıyorsanız --markdown > README.md işareti)

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

Bu durumda önerilen en iyi uygulamalara örnekler verebilir misiniz?

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

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 yükleme sonrası ayrıntılı talimat sayfasını içerir.

Bu dosyada hangi içerik var?

• Firebase güvenlik kurallarını ayarlama veya istemci tarafı kodu ekleme gibi kurulum sonrası gerekli görevlerle ilgili ayrıntılı talimatlar (örnek)
• Yüklenen uzantıyı hemen denemeyle ilgili genel talimatlar (örneğin, "konsola gidin, ardından şunu yapın")
• Uzantının nasıl tetikleneceğiyle ilgili temel bilgiler (özellikle HTTP isteğiyle tetiklenen uzantılar için)
• Yüklü uzantının nasıl izleneceğine dair kısa talimatlar (standart metinle başlayın)

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

Firebase konsolu">

Firebase konsolu">

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

  • POSTINSTALL içeriğinin gösterimini incelemek için uzantınızı gerçek bir projeye yüklediğinizden emin olun.

• Uzantınızın kaynak kodu deposu (uzantı dizininin içinde)

POSTINSTALL dosyaları, parametre değerlerine ve uzantıyla ilgili çeşitli işlev değişkenlerine erişebilir. POSTINSTALL içeriği Firebase konsolunda gösterildiğinde parametre veya değişken referansları yerine gerçek değerler gösterilir. POSTINSTALL dosyanızda parametre ve değişkenlere nasıl POSTINSTALL başvuracağınız hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

Bu durumda önerilen en iyi uygulamalara örnekler verebilir misiniz?

• POSTINSTALL dosyasının tüm içeriğini kısa ve öz tutun ancak açıklayıcı olun.
• Farklı görevleri veya kavramları ayırmak için başlıklar kullanarak içeriği bölümlere ayırın.
• Web sitenizde (örnek) veya uzantı deposundaki ek Markdown dosyalarında (örnek) belirli bir iş akışı ya da görevle ilgili ayrıntılı talimatlar yayınlayabilirsiniz.
• Referans parametreleri ve işleve ilişkin değişkenler böylece kullanıcı, yapılandırılmış değerlerini talimatlar bağlamında görür.

Parametrelere ve değişkenlere referans verme

Yükleme işleminden sonra Firebase konsolunda uzantının POSTINSTALL dosyasının içeriği gösterilir. POSTINSTALL dosyanızda parametrelere ve işlevle ilgili değişkenlere (aşağıdaki tabloya bakın) referans veriyorsanız konsol, bu referansları yüklü örnek için gerçek değerlerle doldurur.

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

Ayrıca, aşağıdaki işleve ilişkin değişkenlere yalnızca POSTINSTALL dosyanızda başvurabilirsiniz. Firebase, bu değişkenleri destekleyerek kullanıcılara yükleme sonrası daha kolay rehberlik etmenizi sağlar. Bu değişkenlerin değerleri yükleme işleminden sonra kullanılabildiğinden yalnızca POSTINSTALL dosyasında kullanılabilir.

Bu tabloda function-name, extension.yaml içindeki işlevin 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ınızın kullanıcı dokümanlarında, 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 rehberlik için uzantınızla ilgili aşağıdaki bölümü genişletin.

CHANGELOG dosyası yazma

Bu dosyada hangi 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 yerleştirin. Aksi takdirde, 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österilir?

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