আপনার এক্সটেনশনের জন্য ব্যবহারকারীর ডকুমেন্টেশন তৈরি করুন

প্রতিটি এক্সটেনশনের ডকুমেন্টেশন থাকতে হবে যা ব্যবহারকারীদের শেখায় যে এক্সটেনশনটি কী করে এবং কীভাবে এটি ব্যবহার করতে হয়।

ন্যূনতম, প্রয়োজনীয়, ডকুমেন্টেশন হল এই তিনটি মার্কডাউন ফাইলের সেট:

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

এছাড়াও, আপনি এগুলি তৈরি করার কথাও বিবেচনা করতে পারেন:

  • এক্সটেনশনের সর্বজনীন রিপোজিটরির জন্য একটি README ফাইল।
  • আপনার নিজের ওয়েবসাইটে প্রকাশিত দীর্ঘ-ফর্মের টিউটোরিয়াল, গাইড ও রেফারেন্স এবং আপনার PREINSTALL.md-এ লিঙ্ক করা।

কিছু পেশাদার পদ্ধতি এবং সাধারণ বাক্যাংশ ও গঠন সম্পর্কে জানতে, আমরা অফিসিয়াল Firebase এক্সটেনশন-এর সাথে উপলভ্য ফাইলগুলি পর্যালোচনা করার সাজেশন দিই।

README তৈরি করা হচ্ছে

আপনার এক্সটেনশন ডিরেক্টরিতে ঐচ্ছিকভাবে একটি README থাকতে পারে। মনে রাখবেন যে firebase ext:dev:init কমান্ড আপনার জন্য অটোমেটিক কোনও কিছু তৈরি করে না।

তবে, Firebase CLI-তে নিম্নলিখিত সুবিধাজনক কমান্ড কাজ করে যার মাধ্যমে আপনার extension.yaml ফাইল এবং PREINSTALL.md ফাইল থেকে কন্টেন্ট নিয়ে README ফাইল অটোমেটিক জেনারেট করা যায়:

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 কনসোল">
Firebase কনসোলে কন্টেন্ট প্রি-ইনস্টল করুন

<span class=Firebase কনসোল">

  • extensions.dev-এ এক্সটেনশনের পৃষ্ঠায়।
  • আপনার এক্সটেনশনের জন্য সোর্স কোড রেপো (এক্সটেনশন ডিরেক্টরির মধ্যে)
  • এক্সটেনশনের README-এর অংশ হিসেবে (আপনি Firebase CLI --markdown > README.md ফ্ল্যাগ ব্যবহার করলে)

PREINSTALL ফাইল এক্সটেনশনের জন্য প্যারামিটারের মান অ্যাক্সেস করতে পারে না, তাই আপনি আশা করবেন না যে প্যারামিটারের রেফারেন্স আসল মানের সাথে রেন্ডার হবে।

কিছু পেশাদার পদ্ধতি কী কী?

  • সম্ভব হলে, PREINSTALL ফাইলের সম্পূর্ণ কন্টেন্ট এক পৃষ্ঠার মধ্যে রাখুন
  • এক্সটেনশন ইনস্টল করার আগে ব্যবহারকারীর অবশ্যই জানা প্রয়োজন এমন বিস্তারিত তথ্য প্রদান করুন
  • POSTINSTALL ফাইল বা অন্যান্য সাপ্লিমেন্টারি ফাইলে বিস্তারিত নির্দেশাবলী লিখুন
  • এক্সটেনশনকে সাহায্য করার জন্য আপনি অন্য কোনও টুল বা স্ক্রিপ্ট প্রদান করলে, তা সংক্ষেপে উল্লেখ করুন

POSTINSTALL ফাইল তৈরি করা হচ্ছে

POSTINSTALL ফাইলটি হল আপনার এক্সটেনশনের বিস্তারিত পোস্ট-ইনস্টলেশন নির্দেশনামূলক পৃষ্ঠা।

এই ফাইলে কী কন্টেন্ট আছে?

  • ইনস্টলেশন-পরবর্তী যেকোনও প্রয়োজনীয় কাজের জন্য বিস্তারিত নির্দেশাবলী, যেমন Firebase নিরাপত্তা সংক্রান্ত নিয়ম সেট-আপ করা বা ক্লায়েন্ট-সাইড কোড যোগ করা (উদাহরণ)
  • ইনস্টল করা এক্সটেনশন কীভাবে অবিলম্বে ব্যবহার করে দেখতে হবে সেই সংক্রান্ত সাধারণ নির্দেশাবলী (যেমন, "কনসোলে যান, তারপর এটি করুন")
  • এক্সটেনশন কীভাবে ট্রিগার করতে হয় সেই সম্পর্কে প্রাথমিক তথ্য, বিশেষ করে HTTP অনুরোধ-ট্রিগার করা এক্সটেনশনের জন্য
  • ইনস্টল করা এক্সটেনশন কীভাবে মনিটর করতে হয় তার সংক্ষিপ্ত নির্দেশাবলী (বয়লারপ্লেট টেক্সট দিয়ে শুরু করুন)

ব্যবহারকারীকে এই কন্টেন্ট কোথায় দেখানো হয়?

<span class= এ পোস্ট-ইনস্টল কন্টেন্টের ছবিFirebase কনসোল">
Firebase কনসোলে ইনস্টল-পরবর্তী কন্টেন্ট

<span class=Firebase কনসোল">

  • ব্যবহারকারী আপনার এক্সটেনশন ইনস্টল করার পরে Firebase কনসোলে (ইনস্টল করা এক্সটেনশনের বিবরণ কার্ডে)

  • আপনার এক্সটেনশনের জন্য সোর্স কোড রেপো (এক্সটেনশন ডিরেক্টরির মধ্যে)

POSTINSTALL ফাইল, এক্সটেনশনের জন্য প্যারামিটারের মান এবং ফাংশন-সম্পর্কিত বিভিন্ন ভেরিয়েবল অ্যাক্সেস করতে পারে। Firebase কনসোলে POSTINSTALL কন্টেন্ট দেখানো হলে, প্যারামিটার বা ভেরিয়েবল রেফারেন্সের পরিবর্তে আসল ভ্যালু দেখানো হয়। আপনার 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} (শুধুমাত্র HTTP ফাংশনের ক্ষেত্রে প্রযোজ্য)
চূড়ান্ত ডেপ্লয় করা ফাংশনের URL, যেখানে ক্লায়েন্ট কোড HTTP অনুরোধ করতে পারে

সাধারণ ফর্ম্যাট:
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 ফাইল থাকতে হবে যা আপনার প্রকাশিত এক্সটেনশনের প্রতিটি নতুন ভার্সনে অন্তর্ভুক্ত পরিবর্তনগুলি ডকুমেন্ট করে। প্রতিটি ভার্সন লেভেল ২ হেডারের (##) অধীনে রাখুন; অন্যথায়, আপনি যেকোনও মার্কডাউন ফরম্যাটিং ব্যবহার করতে পারেন।

নিচে দেওয়া উদাহরণটি হল অফিসিয়াল এক্সটেনশনের একটি উদ্ধৃতি:

## 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 কনসোল এবং CLI-তে, ব্যবহারকারীরা আপনার এক্সটেনশনের নতুন ভার্সনে আপগ্রেড করলে। Firebase কনসোল এবং CLI শুধুমাত্র সেই পরিবর্তনগুলি দেখায় যা ব্যবহারকারী আপগ্রেড সম্পূর্ণ করলে কার্যকর হবে।
  • আপনার এক্সটেনশনের সোর্স কোড রেপো (এক্সটেনশন ডিরেক্টরির মধ্যে)।