अपने एक्सटेंशन के लिए उपयोगकर्ता दस्तावेज़ बनाएं

हर एक्सटेंशन के लिए, दस्तावेज़ होना ज़रूरी है. इसमें उपयोगकर्ताओं को यह जानकारी दी जानी चाहिए कि एक्सटेंशन क्या काम करता है और उसे कैसे इस्तेमाल किया जाता है.

कम से कम ज़रूरी दस्तावेज़, तीन मार्कडाउन फ़ाइलों का यह सेट है:

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

इसके अलावा, आपको इस तरह का कॉन्टेंट बनाने के बारे में भी सोचना चाहिए:

  • एक्सटेंशन के सार्वजनिक डेटाबेस के लिए एक README फ़ाइल.
  • ज़्यादा जानकारी वाले ट्यूटोरियल, गाइड, और रेफ़रंस, जो आपकी वेबसाइट पर पब्लिश किए गए हों और आपके PREINSTALL.md में लिंक किए गए हों.

सबसे सही तरीके और आम तौर पर इस्तेमाल होने वाले वाक्यांश और स्ट्रक्चर जानने के लिए, हमारा सुझाव है कि आप आधिकारिक Firebase एक्सटेंशन के साथ उपलब्ध फ़ाइलों की समीक्षा करें.

README बनाना

आपकी एक्सटेंशन डायरेक्ट्री में README फ़ाइल शामिल की जा सकती है. हालांकि, ऐसा करना ज़रूरी नहीं है. ध्यान दें कि firebase ext:dev:init कमांड, आपके लिए अपने-आप कोई कमांड जनरेट नहीं करता.

हालांकि, Firebase सीएलआई में, यहां दिए गए कमांड का इस्तेमाल करके, README फ़ाइल को अपने-आप जनरेट किया जा सकता है. इस फ़ाइल में, आपकी extension.yaml फ़ाइल और PREINSTALL.md फ़ाइल से लिया गया कॉन्टेंट शामिल होता है:

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

आधिकारिक Firebase एक्सटेंशन के लिए सभी README फ़ाइलें, इस निर्देश का इस्तेमाल करके जनरेट की जाती हैं.

इंस्टॉलेशन की जानकारी जोड़ना

README फ़ाइल लिखने या जनरेट करने के बाद, उसमें इंस्टॉल करने की जानकारी जोड़ें. टेंप्लेट के तौर पर, इस स्निपेट का इस्तेमाल किया जा सकता है:

---

## 🧩 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 फ़ाइल बनाई जा रही है

PREINSTALL फ़ाइल, आपके एक्सटेंशन की खास जानकारी होती है. यह एक तरह का "मार्केटिंग" पेज होता है.

इस फ़ाइल में किस तरह का कॉन्टेंट है?

  • आपके एक्सटेंशन की सुविधाओं के बारे में पूरी जानकारी
  • ज़रूरी शर्तों की सूची, जैसे कि डेटाबेस सेटअप या Google से बाहर की किसी सेवा का ऐक्सेस (उदाहरण)
  • इंस्टॉल करने से पहले किए जाने वाले टास्क और उनके निर्देशों की कम शब्दों में जानकारी
  • इंस्टॉल करने के बाद किए जाने वाले टास्क की खास जानकारी (उदाहरण) (ज़्यादा जानकारी वाले निर्देश POSTINSTALL में दिए गए हैं)
  • बिलिंग पर पड़ने वाले असर के बारे में कम शब्दों में जानकारी (बॉयलरप्लेट टेक्स्ट से शुरू करें)

यह कॉन्टेंट उपयोगकर्ता को कहां दिखता है?

<span class= में पहले से इंस्टॉल किए गए कॉन्टेंट की इमेजFirebase console">
Firebase console में कॉन्टेंट को पहले से इंस्टॉल करना

<span class= में पहले से इंस्टॉल किए गए कॉन्टेंट की बड़ी इमेजFirebase console">

  • extensions.dev पर एक्सटेंशन के पेज पर.
  • आपके एक्सटेंशन के लिए सोर्स कोड रेपो (एक्सटेंशन डायरेक्ट्री के अंदर)
  • एक्सटेंशन के README के हिस्से के तौर पर (अगर Firebase सीएलआई --markdown > README.md फ़्लैग का इस्तेमाल किया जाता है)

PREINSTALL फ़ाइलें, एक्सटेंशन के लिए पैरामीटर वैल्यू को ऐक्सेस नहीं कर सकतीं. इसलिए, आपको यह उम्मीद नहीं करनी चाहिए कि पैरामीटर रेफ़रंस, असल वैल्यू के साथ रेंडर होंगे.

सबसे सही तरीके क्या हैं?

  • अगर मुमकिन हो, तो PREINSTALL फ़ाइल का पूरा कॉन्टेंट एक पेज में रखें
  • एक्सटेंशन इंस्टॉल करने से पहले, असली उपयोगकर्ता को ज़रूरी जानकारी दें
  • POSTINSTALL फ़ाइल या अन्य पूरक फ़ाइलों में पूरी जानकारी दें
  • अगर एक्सटेंशन के साथ काम करने के लिए अन्य टूल या स्क्रिप्ट उपलब्ध कराई जाती हैं, तो उनके बारे में कम शब्दों में बताएं

POSTINSTALL फ़ाइल बनाई जा रही है

POSTINSTALL फ़ाइल, आपके एक्सटेंशन को इंस्टॉल करने के बाद, उसके बारे में ज़्यादा जानकारी देने वाला पेज है.

इस फ़ाइल में किस तरह का कॉन्टेंट है?

  • इंस्टॉल करने के बाद, ज़रूरी टास्क के लिए सिलसिलेवार निर्देश. जैसे, Firebase के सुरक्षा नियम सेट अप करना या क्लाइंट-साइड कोड जोड़ना (उदाहरण)
  • इंस्टॉल किए गए एक्सटेंशन को तुरंत आज़माने के लिए सामान्य निर्देश (उदाहरण के लिए, "कंसोल पर जाएं, फिर यह करें")
  • एक्सटेंशन को ट्रिगर करने के तरीके के बारे में बुनियादी जानकारी. खास तौर पर, एचटीटीपी अनुरोध से ट्रिगर होने वाले एक्सटेंशन के लिए
  • इंस्टॉल किए गए एक्सटेंशन को मॉनिटर करने के तरीके के बारे में कम शब्दों में निर्देश (बॉयलरप्लेट टेक्स्ट से शुरू करें)

यह कॉन्टेंट उपयोगकर्ता को कहां दिखता है?

<span class= में इंस्टॉल करने के बाद मिलने वाले कॉन्टेंट की इमेजFirebase console">
Firebase console में, इंस्टॉल करने के बाद दिखने वाला कॉन्टेंट

<span class= में, इंस्टॉल करने के बाद मिलने वाले कॉन्टेंट की बड़ी इमेजFirebase console">

  • जब कोई उपयोगकर्ता आपका एक्सटेंशन इंस्टॉल कर लेता है, तो Firebase कंसोल में (इंस्टॉल किए गए एक्सटेंशन के जानकारी वाले कार्ड में)

  • आपके एक्सटेंशन के लिए सोर्स कोड रेपो (एक्सटेंशन डायरेक्ट्री के अंदर)

POSTINSTALL फ़ाइलें, एक्सटेंशन के लिए पैरामीटर वैल्यू और फ़ंक्शन से जुड़े कई वैरिएबल ऐक्सेस कर सकती हैं. जब POSTINSTALL कॉन्टेंट को Firebase कंसोल में दिखाया जाता है, तो पैरामीटर या वैरिएबल रेफ़रंस के बजाय असल वैल्यू दिखती हैं. अपनी POSTINSTALL फ़ाइल में पैरामीटर और वैरिएबल को रेफ़रंस के तौर पर इस्तेमाल करने के तरीके के बारे में ज़्यादा जानने के लिए, यहां दी गई जानकारी पढ़ें.

सबसे सही तरीके क्या हैं?

  • POSTINSTALL फ़ाइल के पूरे कॉन्टेंट को छोटा रखें, लेकिन उसमें पूरी जानकारी दें.
  • अलग-अलग टास्क या कॉन्सेप्ट को अलग-अलग दिखाने के लिए, हेडिंग का इस्तेमाल करके कॉन्टेंट को सेक्शन में बांटें.
  • अपनी वेबसाइट (उदाहरण) पर किसी खास वर्कफ़्लो या टास्क के लिए, सिलसिलेवार निर्देश पब्लिश करें. इसके अलावा, एक्सटेंशन रिपॉज़िटरी (उदाहरण) में मौजूद, मार्कडाउन फ़ाइलों में भी निर्देश पब्लिश किए जा सकते हैं.
  • रेफ़रंस पैरामीटर और फ़ंक्शन से जुड़े वैरिएबल, ताकि उपयोगकर्ता को निर्देशों के हिसाब से कॉन्फ़िगर की गई वैल्यू दिखें

पैरामीटर और वैरिएबल का रेफ़रंस देना

इंस्टॉलेशन के बाद, Firebase कंसोल में एक्सटेंशन की POSTINSTALL फ़ाइल का कॉन्टेंट दिखता है. अगर आपने अपनी POSTINSTALL फ़ाइल में पैरामीटर और फ़ंक्शन से जुड़े वैरिएबल (नीचे दी गई टेबल देखें) का रेफ़रंस दिया है, तो कंसोल इन रेफ़रंस को इंस्टॉल किए गए इंस्टेंस की असल वैल्यू से भर देता है.

इस सिंटैक्स का इस्तेमाल करके, POSTINSTALL फ़ाइल में कॉन्फ़िगर की गई पैरामीटर वैल्यू ऐक्सेस करें: ${param:PARAMETER_NAME}

सिर्फ़ अपनी POSTINSTALL फ़ाइल में, फ़ंक्शन से जुड़े इन वैरिएबल का भी रेफ़रंस दिया जा सकता है. Firebase इन वैरिएबल के साथ काम करता है, ताकि आप ऐप्लिकेशन इंस्टॉल करने के बाद, उपयोगकर्ताओं को आसानी से निर्देश दे सकें. इन्हें सिर्फ़ POSTINSTALL फ़ाइल में इस्तेमाल किया जा सकता है, क्योंकि इन वैरिएबल की वैल्यू, इंस्टॉलेशन के बाद ही उपलब्ध होती हैं.

इस टेबल में, function-name, extension.yaml में मौजूद फ़ंक्शन के रिसॉर्स ऑब्जेक्ट में, name फ़ील्ड की वैल्यू है.

फ़ंक्शन से जुड़े वैरिएबल का रेफ़रंस ब्यौरा वैरिएबल वैल्यू (एक्सटेंशन इंस्टॉल होने के बाद, Firebase अपने-आप भरता है)
${function:function-name.location}
जगह जहां फ़ंक्शन को डिप्लॉय किया गया है वैल्यू का उदाहरण:
us-central1
${function:function-name.name}
डिप्लॉय किए गए फ़ाइनल फ़ंक्शन का नाम, जिसमें एक्सटेंशन का इंस्टेंस आईडी शामिल होता है

सामान्य फ़ॉर्मैट:
ext-extension-instance-id-function-name

वैल्यू का उदाहरण:
ext-my-awesome-extension-6m31-yourFunctionName

${function:function-name.url} (सिर्फ़ एचटीटीपी फ़ंक्शन के लिए लागू)
डिप्लॉय किए गए फ़ाइनल फ़ंक्शन का यूआरएल, जिस पर क्लाइंट कोड, एचटीटीपी अनुरोध कर सकता है

सामान्य फ़ॉर्मैट:
https://deployment-location-project-id.cloudfunctions.net/name-of-final-deployed-function

वैल्यू का उदाहरण:
https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

एक्सटेंशन को ट्रिगर करने का तरीका बताना

आपको अपने एक्सटेंशन के उपयोगकर्ता दस्तावेज़ में, उपयोगकर्ताओं को यह बताना होगा कि वे आपके एक्सटेंशन को कैसे ट्रिगर करें. इन निर्देशों में उतनी जानकारी शामिल की जा सकती है जितनी आपको ज़रूरी लगती है. हालांकि, POSTINSTALL फ़ाइल लिखने के सबसे सही तरीके ध्यान में रखें. इन निर्देशों को देने का तरीका जानने के लिए, नीचे दिए गए उस सेक्शन को बड़ा करें जो आपके एक्सटेंशन पर लागू होता है.

CHANGELOG फ़ाइल लिखना

इस फ़ाइल में किस तरह का कॉन्टेंट है?

हर एक्सटेंशन में एक CHANGELOG.md फ़ाइल होनी चाहिए. इसमें आपके एक्सटेंशन के हर नए वर्शन में किए गए बदलावों की जानकारी होनी चाहिए. हर वर्शन को लेवल 2 हेडर (##) के अंदर रखें. इसके अलावा, अपनी पसंद के मुताबिक मार्कडाउन फ़ॉर्मैटिंग का इस्तेमाल किया जा सकता है.

यहां दिया गया उदाहरण, आधिकारिक एक्सटेंशन में से एक का अंश है:

## 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.

यह कॉन्टेंट उपयोगकर्ता को कहां दिखता है?

  • Firebase कंसोल और सीएलआई में, जब उपयोगकर्ता आपके एक्सटेंशन के नए वर्शन पर अपग्रेड करते हैं. Firebase कंसोल और सीएलआई में सिर्फ़ वे बदलाव दिखते हैं जो उपयोगकर्ता के अपग्रेड पूरा करने पर लागू होंगे.
  • आपके एक्सटेंशन की सोर्स कोड रिपॉज़िटरी (एक्सटेंशन डायरेक्ट्री के अंदर).