পরিষ্কার হ্যান্ডঅফের জন্য AI-নির্মিত কোডবেস এক্সপোর্ট চেকলিস্ট

হ্যান্ডঅফের পর এক্সপোর্ট করা প্রজেক্টগুলো কেন ব্যর্থ হয়

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

একটি পরিষ্কার হ্যান্ডঅফ মানে প্রজেক্টটি ক্লোন করা, কনফিগার করা এবং সেই কেউ চালাতে পারবে যিনি তা বানায়নি — একটি নতুন মেশিনে, দীর্ঘ ব্যাক-অ্যান্ড-ফোথ ছাড়াই। এটি নিখুঁত কোড চাই না। এটি মূল বিষয়গুলোকে স্পষ্ট ও পুনরাবৃত্তিযোগ্য করে তুলতে হয়।

এক্সপোর্টগুলো প্রায়ই একই সমস্যায় ভেঙে পড়ে: লুকানো কনফিগারেশন, অনিশ্চিত সিক্রেট হ্যান্ডলিং, অস্পষ্ট লোকাল সেটআপ ধাপ, ডাটাবেসের আচরণ, এবং এমন CI যা কেবল এক পরিবেশেই কাজ করে।

এই কারণেই একটি AI-নির্মিত কোডবেস এক্সপোর্ট চেকলিস্ট মূলত ডকুমেন্টেশন এবং পুনরাবৃত্তিযোগ্যতার উপর মনোনিবেশ করে—কেবল ফাইল কপি নয়। যদি আপনি Koder.ai-র মতো ভাইব-কোডিং প্ল্যাটফর্মে অ্যাপ তৈরি করে সোর্স কোড এক্সপোর্ট করেন, পরের টিমের এখনো একটি মানচিত্র দরকার: কী সেট করতে হবে, কী চালাতে হবে, এবং “কাজ করা” কেমন দেখতে লাগে।

এই চেকলিস্ট হ্যান্ডঅফের মৌলিক বিষয়গুলোতে ফোকাস করে: পরিবেশ ভ্যারিয়েবল, সিক্রেটস, লোকাল ডেভেলপমেন্ট সেটআপ, ডাটাবেস বুটস্ট্র্যাপ, CI সেটআপ, এবং একটি ব্যবহারিক “কিভাবে চালাবেন” README। এটি প্রোডাক্ট সিদ্ধান্ত, UX পালিশ, বা আর্কিটেকচার পুনঃনির্মাণ কভার করে না।

দায়িত্বও স্পষ্ট হওয়া উচিত। নির্মাতা দায়িত্বশীল হয়ে অনুমানগুলো দৃশ্যমান করবেন (ডকস, স্ক্রিপ্ট, নিরাপদ ডিফল্ট)। গ্রহীতার দায়িত্ব হবে প্রজেক্টকে তাদের পরিবেশে মানিয়ে নেওয়া (সিক্রেটস ম্যানেজার, হোস্টিং, কঠোর CI নিয়ম)। যখন উভয় পক্ষ তাদের কাজ জানে, হ্যান্ডঅফ রুটিন হয়ে ওঠে।

এক্সপোর্টের আগে: হ্যান্ডঅফ কনট্রাক্ট ঠিক করুন

একটি পরিষ্কার হ্যান্ডঅফ একটি সরল চুক্তি দিয়ে শুরু হয়: কোড প্ল্যাটফর্ম ছেড়ে গেলে “ডান” মানে কি—এটি নির্ধারণ করুন। না হলে টিমগুলো পরে বলবিতণ্ডায় লিপ্ত হবে: মিসিং স্ক্রিপ্ট, অপ্রত্যাশিত ডিপেন্ডেন্সি, বা কোন ভার্সনই প্রকৃত ছিল।

এক্সপোর্ট করার সময় বেছে নিন

একটি একক স্থিতিশীল পয়েন্ট বেছে নিন এবং সেটিকে সত্যতার উৎস হিসেবে বিবেচনা করুন। পরিবর্তনের মধ্যে এক্সপোর্ট করলে টিমগুলো প্রায়ই এমন একটি রিপো পায় যা প্রায়ই চলে।

ভাল এক্সপোর্ট পয়েন্ট সাধারণত:

• একটি স্থিতিশীল কমিট যার সাথে সংক্ষিপ্ত রিলিজ নোট থাকে (কি বদলেছে, কি টেস্ট করতে হবে)
• একটি ট্যাগ করা রিলিজ (এমনকি v0.1.0 মতো ছোট্ট হলেও)
• একটি প্ল্যাটফর্ম স্ন্যাপশট (উদাহরণ: একটি Koder.ai স্ন্যাপশট যাতে প্রয়োজন হলে রোলব্যাক করা যায়)

এক বাক্যে লিখে রাখুন কেন এই এক্সপোর্ট পয়েন্টটি সঠিক। উদাহরণ: “সব প্রধান ফ্লো পাস করে এবং ডাটাবেস স্কিমা এই মাইলস্টোনের জন্য চূড়ান্ত।”

হ্যান্ডঅফে কী থাকবে তা ঠিক করুন

গ্রহীতার কি আশা করা উচিত তার একটি সংক্ষিপ্ত ইনভেন্টরি লিখুন। কি অন্তর্ভুক্ত এবং কি ইচ্ছাকৃতভাবে বাদ রাখা হয়েছে তা স্পষ্টভাবে বলুন।

বেসিকগুলো অন্তর্ভুক্ত করুন: সোর্স কোড (অ্যাপ, সার্ভিস, শেয়ার্ড প্যাকেজ), কনফিগ টেমপ্লেট (.env.example), স্ক্রিপ্ট (build, dev, test, migrations, seed), এবং ডেপ্লয়মেন্ট নোট। শুধুমাত্র স্যাম্পল ডেটা রাখবেন যদি এটি স্ক্রাব করা ও নিরাপদ হয়।

পর তার পর ভার্সনগুলো ফ্রিজ করুন যাতে “আমার মেশিনে চলে” আর নতুন বেসলাইন না হয়। রানটাইম ও টুলচেইন ভার্সন (Node, Go, Flutter, প্যাকেজ ম্যানেজার) এবং ডাটাবেস ভার্সন (PostgreSQL এর মেজ়র ভার্সন গুরুত্বপূর্ণ) ক্যাপচার করুন।

সবশেষে, প্লে-রেকুইজিটগুলি তালিকাভুক্ত করুন যা কিছু চালানোর আগে করতে হবে। সংক্ষিপ্ত ও কংক্রিট রাখুন: প্রয়োজনীয় অ্যাকাউন্ট, ইনস্টল করা টুল, কোন পোর্ট ফ্রিও থাকতে হবে, এবং যেকোন এক-টাইম সেটআপ স্টেপ।

পরিবেশ ভ্যারিয়েবল: কিছুই লুকিয়ে রাখবেন না

অধিকাংশ “প্ল্যাটফর্মে চলছিল” এক্সপোর্ট ব্যর্থ হয় কারণ মূল সেটিংস ডকুমেন্ট করা হয়নি। পরিবেশ ভ্যারিয়েবল সাধারণত এর মূল কারণ: তারা রিপো-র বাইরে থাকে, তাই নতুন টিমমেম্বার ক্লোন করলে কোন মান প্রত্যাশিত তা জানে না।

একটি পরিষ্কার এক্সপোর্টের জন্য: প্রতিটি ভ্যারিয়েবল আবিষ্কারযোগ্য, ব্যাখ্যাযোগ্য এবং অনুমান ছাড়াই সেট করা সহজ হওয়া উচিত।

হ্যান্ডঅফ README-এ একটি একক সত্যতার উৎস নির্মাণ করুন: ভ্যারিয়েবল নামের তালিকা, এটি অ্যাপে কী নিয়ন্ত্রণ করে, এবং মান কোথা থেকে আসে। ব্যাখ্যাগুলো সাধারণ ভাষায় রাখুন এবং যেকোন নিরাপত্তা-সংক্রান্ত বিষয় আলাদা করে দেখান।

প্রতিটি ভ্যারিয়েবলের জন্য একটি সহজ ফর্ম্যাট:

• Name: সঠিক কি (কপি/পেস্ট-বন্ধুবৎসল)
• Meaning: অ্যাপে এটি কী পরিবর্তন করে
• Required?: প্রয়োজনীয় নাকি ঐচ্ছিক (এবং অনুপস্থিত হলে কি হয়)
• Example: নিরাপদ উদাহরণ মান (কখনওই প্রকৃত সিক্রেট নয়)
• Where it differs: dev বনাম staging বনাম production

এর পাশাপাশি .env.example ফাইল রিপোতে রাখুন। এতে প্রতিটি সম্ভবত দরকারি ভ্যারিয়েবল থাকতে হবে, নিরাপদ প্লেসহোল্ডার মানসহ যাতে অ্যাপ সামান্য সম্পাদনায় চালু করা যায়।

# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev

# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173

# Environment specific
PUBLIC_BASE_URL=http://localhost:3000

কিছু বিস্তারিত নিয়ম বেশিরভাগ বিভ্রান্তি রোধ করে:

“প্রয়োজনীয় বনাম ঐচ্ছিক” স্পষ্ট করুন। কোন ভ্যারিয়েবল অনুপস্থিত হলে ক্র্যাশ হয়, তা বলুন। যদি এটি একটি ফিচার চালায় (ইমেল পাঠানো, পেমেন্ট, ফাইল স্টোরেজ), ফিচারটির নাম দিন এবং অনুপস্থিত হলে কী হয় তা বর্ণনা করুন।

পরিবেশভেদে কি বদলায় তা উল্লেখ করুন। DATABASE_URL ও PUBLIC_BASE_URL সাধারণত dev, staging, production-এ ভিন্ন হয়, আর LOG_LEVEL হয়ত সারাব্যাপী একই থাকে। যদি আপনি Koder.ai-এ এক্সপোর্ট ও ডেপ্লয় করতেন, প্ল্যাটফর্ম ডিফল্ট (পোর্ট, বেস URL, অনুমোদিত অরিজিন) ডকুমেন্টে প্রতিফলিত আছে কিনা চেক করুন যাতে প্ল্যাটফর্মের বাইরে আচরণ কনসিস্টেন্ট থাকে।

অবশেষে, লোকালভাবে env ভ্যারিয়েবল কিভাবে লোড হয় তা বলুন। প্রকল্প যদি .env ফাইল প্রত্যাশা করে, কোথায় থাকে এবং অ্যাপ তা স্বয়ংক্রিয়ভাবে পড়ে নেয় নাকি কোন কমান্ড/টুল দরকার তা লিখে রাখুন।

সিক্রেটস: রিপো-র বাইরে রাখুন এবং সেট করা সহজ করুন

সিক্রেটসগুলোই এমন মান যা লিক হলে ক্ষতি করতে পারে: API কী, ডাটাবেস পাসওয়ার্ড, অথ টোকেন, OAuth ক্লায়েন্ট সিক্রেট, প্রাইভেট কী, webhook সাইনিং সিক্রেট ইত্যাদি।

এক্সপোর্টের জন্য সরল রাখুন: রিপোতে কেবল প্লেসহোল্ডার রাখুন, কখনই বাস্তব সিক্রেট রাখবেন না। যদি কোন সিক্রেট চালাতে প্রয়োজন হয়, .env.example-এ সুস্পষ্ট নামযুক্ত প্লেসহোল্ডার রাখুন এবং একটি বাস্তব কী কিভাবে জেনারেট করবেন তা ব্যাখ্যা করুন।

একটি ব্যবহারিক প্যাটার্ন হলো তিনটি জিনিস আলাদা রাখা: স্যাম্পল ফাইল, লোকাল ফাইল, এবং CI/ডেপ্লয়মেন্ট সিক্রেট স্টোর। আপনার এক্সপোর্ট করা কোডে স্যাম্পল থাকা উচিত, লোকাল ফাইল .gitignore করা উচিত, এবং CI/হোস্টিং কীভাবে সিক্রেট পায় তা ডকুমেন্ট করুন।

কোন পরিবেশে সিক্রেট কোথায় রাখা উচিত

একটি পদ্ধতি প্রতিটি পরিবেশের জন্য বেছে নিন এবং সেটিতে স্থির থাকুন।

• লোকাল ডেভেলপমেন্ট: .env (gitignored) অ্যাপ দ্বারা লোড করা, বা টিমের লোকাল সিক্রেট ম্যানেজার
• CI: CI প্রোভাইডারের এনক্রিপ্টেড সিক্রেট ভ্যারিয়েবল
• ডেপ্লয়মেন্ট/হোস্টিং: হোস্টিং পরিবেশে সিক্রেট সঞ্চিত এবং রানটাইমে ইনজেক্ট করা

উদাহরণ: রিপোতে থাকবে PAYMENTS_API_KEY=replace_me। গ্রহীতা তাদের প্রোভাইডার ড্যাশবোর্ডে নিজের কী জেনারেট করে লোকাল .env ও CI-তে সেট করবে। কোড অপরিবর্তিত থাকবে।

রোটেশন স্টেপ যোগ করুন

হ্যান্ডঅফ হল সিক্রেট রোটেট করার উপযুক্ত সময়, বিশেষ করে যদি সেগুলো কখনও শেয়ার করা হয় বা প্ল্যাটফর্ম সেশনেই ব্যবহার করা হয়ে থাকে।

• এক্সটার্নাল সার্ভিসের জন্য নতুন কী পুনরায় ইস্যু করুন ও পুরোনোগুলো বাতিল করুন।
• ডাটাবেস পাসওয়ার্ড ও কোনো অ্যাডমিন টোকেন রিসেট করুন।
• প্রথমে CI ও হোস্টিং সিক্রেট আপডেট করুন, তারপর লোকাল .env ফাইলগুলো আপডেট করুন।
• নিশ্চিত করুন অ্যাপ চালু হয়, টেস্ট পাস করে, এবং পুরোনো কী আর কাজ করে না।

আপনি যদি Koder.ai থেকে এক্সপোর্ট করে থাকেন, এক্সপোর্টকে একটি নতুন পরিবেশ হিসেবে বিবেচনা করুন এবং গ্রহীতা টিমের জন্য নতুন সিক্রেট জেনারেট করুন।

লোকাল ডেভেলপমেন্ট সেটআপ: প্রথম রানকে বিরক্তিকর করে তুলুন

হ্যান্ডঅফ সফল তখনই যখন নতুন ডেভেলপার ক্লোন করে কয়েকটি কমান্ড চালিয়ে অ্যাপটি কাজ করে দেখেন—অনুমান ছাড়াই। পূর্বানুমানহীন প্রয়োজনীয়তা, একটি স্পষ্ট কমান্ড অর্ডার, এবং একটি ছোট “কিভাবে চালাবেন” ব্লক দিন যা বাস্তবতার সাথে মিলে।

প্রয়োজনীয়তা (স্পষ্টভাবে জানাবেন)

README এর শীর্ষে এগুলো রাখুন যাতে কেউ ত্রুটি মেসেজ থেকে অনুমান করতে না হয়:

• OS নোট: “macOS ও Ubuntu-এ টেস্ট করা” (Windows নোট রাখবেন কেবল যদি সেটা টেস্ট করে থাকেন)
• রানটাইম ভার্সন: Node.js (React-এর জন্য), Go (API-এর জন্য), PostgreSQL (DB-এর জন্য)
• টুলস: npm/pnpm/yarn, Make (আপনি যদি ব্যবহার করেন), Docker (শুধু যদি আপনি তার উপর নির্ভর করেন)

প্রজেক্ট যদি Koder.ai-এ তৈরি হয়েছিল, লোকাল সেটআপ এক্সপোর্টের সাথে সঙ্গত রাখুন (ওই একই ফোল্ডার স্ট্রাকচার, একই স্টার্ট কমান্ড)। “Postgres ইতিমধ্যে চলছে” এমন অনুমান করবেন না যদি না আপনি তা স্পষ্ট লিখেন।

ইনস্টলেশন ও ডেভ কমান্ড (প্রতিটি লাইনে এক কমান্ড)

নতুন টিমমেটকে যা চালাতে হবে তা সঠিক ক্রমে, কপি-পেস্টযোগ্যভাবে দিন:

# 1) Install dependencies
cd web
npm ci

cd ../server
go mod download

# 2) Create your env file
cp .env.example .env

# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose

# 4) Run the app
cd server
go run ./cmd/api

cd ../web
npm run dev

তারপর একটি ন্যূনতম টেস্ট ও বিল্ড সেকশন যোগ করুন:

# Tests
cd server \u0026\u0026 go test ./...
cd web \u0026\u0026 npm test

# Build
cd web \u0026\u0026 npm run build
cd server \u0026\u0026 go build ./...

Troubleshooting: প্রথম রান-এর সাধারণ ব্যর্থতা

অধিকাংশ “চলছে না” সমস্যা কয়েকটি ক্যাটাগরিতে পড়ে:

1. ভুল ভার্সন (Node/Go)। লক্ষণ: ডিপেন্ডেন্সি বা কম্পাইল ত্রুটি। সমাধান: নির্দিষ্ট ভার্সন ইনস্টল করে ইনস্টলেশনগুলো পুনরায় চালান।

2. অনুপস্থিত env মান। লক্ষণ: “undefined” কনফিগ, অথ ব্যর্থতা, 500 এরর। সমাধান: .env-কে .env.example-এর সাথে তুলনা করে প্রয়োজনীয় মান ভরুন।

3. ডাটাবেস অ্যাক্সেস পাচ্ছে না। লক্ষণ: connection refused, “database does not exist.” সমাধান: Postgres চালান, হোস্ট/পোর্ট/ইউজার যাচাই করুন, এবং ডাটাবেস ইনিট ধাপগুলো সঠিকভাবে চালান।

ডাটাবেস বুটস্ট্র্যাপ: মাইগ্রেশন, সীড, এবং রিসেট

প্ল্যাটফর্ম থেকে এক্সপোর্ট করা হলে ডাটাবেসই প্রায়ই প্রথম জায়গা যেখানে নতুন মেশিনে ভেঙে যায়। লক্ষ্য সাধারণ: টিমমেটকে “আমি রিপো ক্লোন করলাম” থেকে “অ্যাপ বাস্তবে ডেটা সহ চলছে” অবস্থায় নিয়ে আসা—অনুমান ছাড়াই।

কী ডকুমেন্ট করবেন (এবং রিপোতে রাখুন)

একটি ফ্রেশ PostgreSQL সেটআপের জন্য ন্যূনতম ধাপগুলো লিখে রাখুন এবং সম্ভব হলে কমান্ডগুলো স্ক্রিপ্টে রাখুন। আপনার হ্যান্ডঅফের উত্তর থাকা উচিত চারটি প্রশ্নের:

• কিভাবে ডাটাবেস ও রোল তৈরি করতে হবে (নাম, পারমিশন, পাসওয়ার্ড কোথা থেকে আসে)?
• কিভাবে শূন্য থেকে সর্বশেষ মাইগ্রেশনে মাইগ্রেশন চালাবেন?
• কিভাবে ডেমো চালানোর মতো সীড ডেটা লোড করবেন?
• ডেভেলপমেন্টে কিভাবে নিরাপদে রিসেট করবেন?

যদি আপনার কাছে স্ক্রিপ্ট (Makefile টার্গেট, শেল স্ক্রিপ্ট, টাস্ক রানার কমান্ড) থাকে, সেগুলো ব্যবহার করুন। যদি না থাকে, এখনই ছোট কিছু স্ক্রিপ্ট যোগ করুন।

একটি বিরক্তিকর কিন্তু কাজ করা বুটস্ট্র্যাপ ফ্লো

পরিবেশ জুড়ে (লোকাল, CI, staging) ফ্লো কনসিস্টেন্ট রাখুন। একটি ভাল বেসলাইন দেখতে এমন হবে:

# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user

# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up

# 3) Seed minimal demo data
./scripts/seed

সীডগুলোর জন্য প্রোডাকশন-লাইক ডাম্পের বদলে ন্যূনতম কাজ করা ডেটা রাখুন। সীডগুলো বহুবার চালাতে নিরাপদ হওয়া উচিত (idempotent inserts, অথবা একটি পরিষ্কার “শূন্য DB-তে চালাতে” নিয়ম)।

রিসেটগুলোর সময় সুরক্ষা সম্পর্কে স্পষ্ট হন। একটি রিসেট কমান্ড ডিফল্টভাবে কেবল লোকাল ডেভেলপমেন্ট লক্ষ্য করে থাকা উচিত। যদি আপনি ধ্বংসাত্মক স্ক্রিপ্ট দেন, একটি গার্ডরেইল যোগ করুন (উদাহরণ: CONFIRM_RESET=1 থাকা বা APP_ENV=development চেক)। এছাড়াও নির্দিষ্ট করুন “রিসেট” মানে কী: ড্রপ ও পুনরায় তৈরি, টেবিল মুছা, অথবা একটি নির্দিষ্ট স্ন্যাপশট রিস্টোর।

রিপো পরিচ্ছন্নতা: সোর্সে কী থাকা উচিত এবং কী নয়

হ্যান্ডঅফ তখনই গন্ডগোল হয় যখন রিপো একটি জাঙ্ক ড্রয়ারের মত মনে হয়। নতুন কেউ সহজেই বুঝতে পারা উচিত কী গুরুত্বপূর্ণ, কী জেনারেটেড, এবং কোথায় সেটিংস পরিবর্তন করতে হবে।

রিপিটেবল করে তোলার জন্য যা কিছু দরকার তা কমিট করুন: লোকফাইল, মাইগ্রেশন ফাইল, ছোট কনফিগ টেমপ্লেট যেমন .env.example, এবং যে কোনো স্ক্রিপ্ট যা অ্যাপ বুটস্ট্র্যাপ করে।

ব্যক্তিগত, জেনারেটেড বা সংবেদনশীল ফাইল সোর্স কন্ট্রোলে রাখবেন না: লোকাল env ফাইল, এডিটর সেটিংস, বিল্ড আউটপুট, লগ, ক্যাশ, এবং যেকোনও এমন জিনিস যা অ্যাক্সেস দেয় (API কী, DB পাসওয়ার্ড, সার্ভিস অ্যাকাউন্ট ফাইল)।

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

একটি ছোট “রাখুন বনাম ইগনোর” নোট যোগ করলে সংক্ষিপ্ত রাখুন:

• Commit: README, লোকফাইল, মাইগ্রেশন, সীড স্ক্রিপ্ট, .env.example
• Ignore: .env, সিক্রেট ফাইল, বিল্ড ফোল্ডার, লগ, লোকাল ক্যাশ

ডিরেক্টরি ম্যাপ যোগ করুন যাতে স্ট্রাকচার ক্লিক করে দেখতে না হয়েই বোঝা যায়। উদাহরণ: “/backend API সার্ভিস, /web ফ্রন্টএন্ড, /mobile অ্যাপ, /db মাইগ্রেশন ও সীড, /scripts সেটআপ হেলপার।”

আপনি যদি Koder.ai থেকে এক্সপোর্ট করে থাকেন, এক্সপোর্টকে এই ক্লিনআপ পাসের শুরু হিসেবে বিবেচনা করুন: জেনারেটেড ক্লাটার সরান, ইগনোর রুলগুলো নিশ্চিত করুন, এবং ডিরেক্টরি ম্যাপ লিখুন।

CI সেটআপ: পাইপলাইনকে পুনরাবৃত্তিযোগ্য করুন

হ্যান্ডঅফ নিঃশব্দে ব্যর্থ হয় যখন CI কেবল লোকালের মতোই চলছে। যদি কেউ লোকালে প্রজেক্ট চালাতে পারে, CI-ও সেই একই কমান্ডগুলো চালিয়ে একই ফলাফল পাওয়া উচিত।

প্রতি পা’ল রিকুয়েস্টে CI কী প্রমাণ করবে তা নির্ধারণ করুন। বেশিরভাগ টিমের জন্য ছোট একটি সেট যথেষ্ট:

• Lint/format
• Unit tests
• Build (ওয়েব ও সার্ভার কম্পাইল ক্লিন হওয়া)

ইন্টিগ্রেশন টেস্ট এবং ডেপ্লয় স্টেপও ঠিক আছে, কিন্তু কেবল যদি সেগুলো নির্ভরযোগ্য ও স্পষ্টভাবে সীমাবদ্ধ থাকে।

লোকাল কমান্ডগুলোর কাছাকাছি CI স্টেপ রাখুন যাতে ড্রিফ্ট না হয়। লোকালে যদি make test হয়, CI-তেও make test চালান। যদি আপনার কাছে Makefile না থাকে, একটি যোগ করার কথা ভাবুন এবং সেটিকে শেয়ার্ড এন্ট্রি পয়েন্ট হিসেবে ব্যবহার করুন।

env ভ্যারিয়েবল ও সিক্রেটগুলো দেখান

CI সাধারণত ভাঙে কারণ এটি লুকানো কনফিগের ওপর নির্ভর করে। README-তে ছোট একটি “CI variables” সেকশন যোগ করুন যেখানে CI কী নাম আশা করে তা ঠিকভাবে তালিকাভুক্ত থাকবে। পাবলিক কনফিগ আলাদা করে রাখুন সিক্রেট থেকে।

নামগুলোর উদাহরণ (আপনার স্ট্যাক অনুযায়ী সমন্বয় করুন): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. CI-তে সিক্রেটগুলো প্রোভাইডারের সিক্রেট স্টোর থেকে আসবে—কখনই কমিটেড ফাইল থেকে নয়। Go + Postgres ব্যাকএন্ডের ক্ষেত্রে, নোট করুন মাইগ্রেশন স্বয়ংক্রিয়ভাবে চলে কিনা বা একটি স্পষ্ট ধাপ হিসেবে চালাতে হয় কিনা।

মার্জ প্রোটেকশন স্ট্যাটাস চেক দিয়ে করুন

কোন চেকগুলো মার্জের আগে আবশ্যক হবে তা নির্ধারণ করে লিখে রাখুন। “lint + unit tests + build” সাধারণত যথেষ্ট। যদি আপনি ঐচ্ছিক জব (যেমন মোবাইল বিল্ড) যোগ করেন, সেগুলো ব্লকিং না করে রাখুন যতক্ষণ না সত্যিই দরকার।

CI আউটপুটগুলো ডিবাগ করা সহজ রাখুন: টুল ভার্সন প্রিন্ট করুন এবং পরিষ্কার মেসেজ দিয়ে ফেল করুন। পাইপলাইন স্থিতিশীল হলে ক্যাশিং যোগ করুন।

উদাহরণ হ্যান্ডঅফ সিনারিও: ক্লোন থেকে অ্যাপ চলানো পর্যন্ত

Maya Koder.ai থেকে এক্সপোর্ট করা একটি প্রজেক্ট পায়। এটি একটি সাধারণ সেটআপ: React web অ্যাপ, Go API, এবং PostgreSQL ডাটাবেস। তিনি ক্লোন করে বিনা অনুমানেই একটি কাজ করা স্ক্রীনে পৌছাতে পারেন—এটাই উদ্দেশ্য।

তার প্রথম 30 মিঃএর রোডম্যাপ হওয়া উচিত:

1. রিপো ক্লোন করে রুট README খুলুন।
2. .env.example থেকে .env কপি করুন (বা একই মান শেলে সেট করুন) উভয় web ও api ফোল্ডারে।
3. PostgreSQL চালু করুন (লোকালি বা Docker-এ) এবং খালি ডাটাবেস তৈরি করুন।
4. মাইগ্রেশন ও সীড চালিয়ে একটি পরিচিত স্টার্টিং ডেটাসেট পান।
5. ব্যাকেন্ড চালু করুন, তারপর ফ্রন্টেন্ড চালান, এবং ব্রাউজারে অ্যাপ লোড করুন।

একটি গণ্ডগোল হ্যান্ডঅফে তিনি প্রায়শই তিনটি অবরোধে পড়েন।

প্রথমত: অ্যাপ বুট হয়, তারপর একটি অস্পষ্ট “missing config” এরর সহ ক্র্যাশ করে। বাস্তব সমস্যা হয় একটি অনডকুমেন্টেড ভ্যারিয়েবল যেমন AUTH_JWT_SECRET বা এক নির্দিষ্ট DATABASE_URL ফরম্যাট। README যদি প্রতিটি প্রয়োজনীয় ভ্যারিয়েবল তালিকাভুক্ত করে, নিরাপদ উদাহরণ দেখায় এবং কোথায় ব্যবহার হয় তা বলে, তাহলে এটি দ্রুত ঠিক করা যায়।

দ্বিতীয়ত: API চালু আছে, কিন্তু প্রতিটি পেজে “no data” দেখা যায় বা 500 এরর। ডাটাবেস আছে, কিন্তু টেবিল বা সীড ডেটা নেই। একটি পরিষ্কার হ্যান্ডঅফ এক বা দুইটি নির্ভরযোগ্য কমান্ড দেয়: মাইগ্রেশন চালান, ন্যূনতম ডেমো ডেটা সীড করুন, এবং যখন কিছু ভাঙে তখন রিসেট কমান্ড দেওয়া থাকে।

তৃতীয়ত: সবকিছু চলছে, কিন্তু ফ্রন্টেন্ড ভুল পোর্টে পয়েন্ট করছে। Maya localhost:3000 খুলে ফেলে, কিন্তু API localhost:8080 এ প্রত্যাশিত, বা CORS অনুরোধ ব্লক করছে। এখানে কনসিস্টেন্ট ডিফল্ট দরকার: একটি জায়গায় WEB_PORT, API_PORT, এবং API_BASE_URL সেট করার জন্য, README-তে লোকাল URL কিভাবে হওয়া উচিত তা উল্লেখ করে।

চূড়ান্ত চেকলিস্ট, সাধারণ ফাঁদ, এবং পরবর্তী ধাপ

হ্যান্ডঅফ তখনই শেষ যখন কেউ ক্লিন ক্লোন থেকে প্রজেক্ট চালাতে পারে কোনো প্রশ্ন ছাড়াই। প্রমাণ দিন যে প্রজেক্টটি প্ল্যাটফর্মের বাইরে টিকে থাকতে পারে।

ফাইনাল “ক্লিন ক্লোন” টেস্টটি একটি নতুন মেশিন বা একটি টোয়াফঅ্যাজ কনটেইনারে করুন—আপনার বিদ্যমান ফোল্ডার, ক্যাশেড ডিপেন্ডেন্সি, বা লোকাল ডাটাবেস পুনরায় ব্যবহার করবেন না। README নির্দিষ্টভাবে অনুসরণ করুন। আপনার যদি একবারও improvisation করতে হয়, ডক্স বা স্ক্রিপ্ট ঠিক করুন যতক্ষণ না আর improvisation লাগে না।

দ্রুত চেকগুলো যা বেশিরভাগ ফেলিওর ধরবে:

• README-এ একটি একক, কপি-পেস্টযোগ্য “কিভাবে চালাবেন” পথ আছে লোকাল ডেভের জন্য, প্লাস একটি ছোট “কিভাবে টেস্ট করবেন।”
• .env.example আছে, এবং প্রতিটি প্রয়োজনীয় ভ্যারিয়েবল নিরাপদ উদাহরণ মানসহ ব্যাখ্যায় আছে।
• ডাটাবেস বুটস্ট্র্যাপ এন্ড-টু-এন্ড কাজ করে: DB তৈরি, মাইগ্রেশন চালানো, ঐচ্ছিক সীড, এবং একটি রিসেট কমান্ড।
• CI ক্লিন রানারে চলে এবং লোকাল কমান্ডগুলোর সাথে মিলে।
• নতুন ডেভ একটি ছোট পরিবর্তন করে, টেস্ট চালায়, এবং সেটি অ্যাপে দেখা যায়।

সাধারণ ফাঁদগুলো বিরক্তিকর কারণ সেগুলোই মিস হয়ে যায়:

• লুকানো এক-টাইম স্টেপ যা ডক্সে ঢুকেনি
• README পুরোনো ফোল্ডার স্ট্রাকচার বা পুরোনো কমান্ড নামের সাথে মিলে না
• হার্ডকোড করা ভ্যালু (API URL, ফিচার ফ্ল্যাগ, কী) কোডে কনফিগের বদলে
• অনিয়মিতভাবে শেয়ার করা সিক্রেটস যার নিরাপদ সেটআপ পথ নেই
• CI যা কেবল ক্যাশ হওয়া আর্টিফ্যাক্ট বা লোকাল সার্ভিসের ওপর নির্ভর করে পাস করে

পরবর্তী ধাপ: এক ব্যক্তি অ্যাসাইন করুন যে এক্সপোর্ট 24–48 ঘন্টার মধ্যে যাচাই করবে, না সপ্তাহ পর। তাঁকে ক্লিন ক্লোন টেস্ট করতে বলুন এবং ফাঁক রিপোর্ট করতে বলুন।

আপনি যদি Koder.ai-এ বিল্ড করে থাকেন (koder.ai), এই চেকলিস্টকে আপনার নিয়মিত ওয়ার্কফ্লো-র অংশ হিসেবে বিবেচনা করলে সুবিধা হবে: প্ল্যানিং মোডে রান পাথ লিখে রাখুন, বড় পরিবর্তনের আগে স্ন্যাপশট নিন, এবং সময়নিয়মে সোর্স এক্সপোর্ট করুন যাতে হ্যান্ডঅফ প্যাকেজ আপ-টু-ডেট থাকে।