हर एक्सटेंशन के लिए दस्तावेज़ होना ज़रूरी है. इससे उपयोगकर्ताओं को यह पता चलता है कि एक्सटेंशन क्या करता है और उसका इस्तेमाल कैसे किया जाता है.
कम से कम, ज़रूरी दस्तावेज़ों में तीन मार्कडाउन फ़ाइलों का यह सेट शामिल है:
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 लिखने या जनरेट करने के बाद, उसमें इंस्टॉलेशन की जानकारी जोड़ें. टेंप्लेट के तौर पर, यहां दिए गए स्निपेट का इस्तेमाल किया जा सकता है:
--- ## 🧩 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
पर जाएं) - बिलिंग से जुड़े किसी भी असर के बारे में खास जानकारी (बोयलरप्लेट टेक्स्ट से शुरू करें)
उपयोगकर्ता को यह कॉन्टेंट कहां दिखता है?
- extensions.dev पर एक्सटेंशन के पेज पर.
- एक्सटेंशन डायरेक्ट्री में, आपके एक्सटेंशन का सोर्स कोड रेपो
- एक्सटेंशन के README के हिस्से के तौर पर (अगर Firebase सीएलआई
फ़्लैग का इस्तेमाल किया जाता है)--markdown > README.md
PREINSTALL
फ़ाइलें, एक्सटेंशन के लिए पैरामीटर वैल्यू को ऐक्सेस नहीं कर सकतीं. इसलिए, आपको
पैरामीटर रेफ़रंस को असल वैल्यू के साथ रेंडर होने की उम्मीद नहीं करनी चाहिए.
सबसे सही तरीके क्या हैं?
- अगर हो सके, तो
PREINSTALL
फ़ाइल के पूरे कॉन्टेंट को एक पेज के नीचे रखें - एक्सटेंशन इंस्टॉल करने से पहले, उपयोगकर्ता को ज़रूरी जानकारी दें
POSTINSTALL
फ़ाइल या अन्य ज़रूरी फ़ाइलों में ज़्यादा जानकारी वाले निर्देश डालें- अगर एक्सटेंशन के साथ काम करने के लिए, अन्य टूल या स्क्रिप्ट उपलब्ध कराई जाती हैं, तो इसकी जानकारी दें
POSTINSTALL
फ़ाइल में लिखना
POSTINSTALL
फ़ाइल, आपके एक्सटेंशन के इंस्टॉल होने के बाद, निर्देशों वाला पेज होती है.
इस फ़ाइल में कौनसा कॉन्टेंट है?
- इंस्टॉलेशन के बाद किए जाने वाले ज़रूरी टास्क के बारे में ज़्यादा जानकारी देने वाले निर्देश. जैसे, Firebase के सुरक्षा नियम सेट अप करना या क्लाइंट-साइड कोड जोड़ना (उदाहरण)
- इंस्टॉल किए गए एक्सटेंशन को तुरंत आज़माने के सामान्य निर्देश (उदाहरण के लिए, "कंसोल पर जाएं, फिर यह करें")
- एक्सटेंशन को ट्रिगर करने के तरीके के बारे में बुनियादी जानकारी. खास तौर पर, एचटीटीपी अनुरोध से ट्रिगर होने वाले एक्सटेंशन के लिए
- इंस्टॉल किए गए एक्सटेंशन को मॉनिटर करने के तरीके के बारे में कम शब्दों में निर्देश (बोयलरप्लेट टेक्स्ट से शुरू करें)
लोगों को यह कॉन्टेंट कहां दिखता है?
जब कोई उपयोगकर्ता आपका एक्सटेंशन इंस्टॉल करता है, तो Firebase console में (इंस्टॉल किए गए एक्सटेंशन के ज़्यादा जानकारी वाले कार्ड में)
- किसी असली प्रोजेक्ट में अपना एक्सटेंशन इंस्टॉल करके,
POSTINSTALL
कॉन्टेंट के डिसप्ले की समीक्षा करना न भूलें.
- किसी असली प्रोजेक्ट में अपना एक्सटेंशन इंस्टॉल करके,
एक्सटेंशन डायरेक्ट्री में, आपके एक्सटेंशन का सोर्स कोड रेपो
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}
|
||
फ़ाइनल डिप्लॉय किया गया फ़ंक्शन का नाम, जिसमें एक्सटेंशन का इंस्टेंस आईडी शामिल होता है |
सामान्य फ़ॉर्मैट:
वैल्यू का उदाहरण: |
|
${function:function-name.url}
(सिर्फ़ एचटीटीपी फ़ंक्शन के लिए लागू)
|
||
डिप्लॉय किए गए फ़ंक्शन का यूआरएल, जिस पर क्लाइंट कोड एचटीटीपी अनुरोध कर सकता है |
सामान्य फ़ॉर्मैट:
वैल्यू का उदाहरण: |
एक्सटेंशन को ट्रिगर करने का तरीका बताने वाला दस्तावेज़
आपके एक्सटेंशन के उपयोगकर्ता दस्तावेज़ में, आपको अपने उपयोगकर्ताओं को यह निर्देश देना होगा कि
अपना एक्सटेंशन कैसे ट्रिगर करें. इन निर्देशों में ज़रूरत के हिसाब से ज़्यादा जानकारी दी जा सकती है. हालांकि, 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 कंसोल और सीएलआई में सिर्फ़ वे बदलाव दिखते हैं जो उपयोगकर्ता के अपग्रेड पूरा करने पर लागू होंगे.
- आपके एक्सटेंशन का सोर्स कोड रिपॉज़िटरी (एक्सटेंशन डायरेक्ट्री में).