npm paketni nashr qilish oson. Uni yuritish — boshqa masala
npm'ga paket chiqarish uchun uch narsa kerak: kod, package.json va bitta buyruq. Bir kunda bo'ladi.
Men uchta paket chiqarganman. Va ular haqida eng ko'p o'rgangan narsam nashr qilish jarayoni emas — undan keyin nima bo'lishi.
Chunki paket chiqqan zahoti u sizniki bo'lishdan to'xtaydi. Uni odamlar ishlatadi, ularning kodi sizning kodingizga bog'lanadi, va siz endi erkin emassiz.
Bu maqola shu haqda.
Nashrdan oldin: uchta majburiy narsa
Texnik tomoni oson, lekin uchta narsa boshidan to'g'ri bo'lishi kerak, chunki keyin ularni o'zgartirish qimmat.
1. Nima eksport qilinishini aniq belgilang.
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
},
"files": ["dist"]
}files maydoni muhim: usiz paketga sinov fayllari, konfiguratsiyalar va tasodifiy narsalar tushadi. Nashrdan oldin npm pack --dry-run bilan nima ketayotganini ko'ring — bu bir soniyalik odat va u sizni ko'p uyatdan saqlaydi.
2. Bog'liqliklarni minimal qiling.
Har bir bog'liqlik sizning paketingizni ishlatgan odamga majburiy bo'ladi. Kichik yordamchi uchun kutubxona qo'shish o'rniga o'n qator kod yozish deyarli har doim to'g'riroq.
Agar paket biror framework bilan ishlasa, uni peerDependencies ga qo'ying, dependencies ga emas. Aks holda foydalanuvchida frameworkning ikkita nusxasi paydo bo'ladi va tushunarsiz xatolar chiqadi.
3. README birinchi ekranda ishlaydigan misol bilan boshlansin.
Odamlar hujjatni o'qimaydi, ular ko'chiradi. README'ning birinchi yigirma qatorida ishlaydigan, to'liq, nusxa olib qo'yish mumkin bo'lgan misol bo'lsin. Qolgan hamma narsa pastda.
Versiyalash: buzuvchi o'zgarish nima ekanini noto'g'ri tushunish
Semantik versiyalashni hamma biladi: katta raqam — buzuvchi o'zgarish, o'rtasi — yangi qobiliyat, oxirgisi — tuzatish.
Muammo ta'rifda. Ko'pchilik "buzuvchi o'zgarish" deganda faqat API o'zgarishini tushunadi. Aslida ro'yxat ancha uzun:
- Funksiya nomi yoki parametr tartibi o'zgardi — bu aniq
- Standart qiymat o'zgardi — API bir xil, xatti-harakat boshqa
- Xato turi o'zgardi — kimdir
catchichida uni tekshirayotgan bo'lishi mumkin - Node yoki framework minimal versiyasi ko'tarildi — eski muhitdagilar uchun paket ishlamay qoladi
- Chiqish formati o'zgardi — masalan qaytariladigan obyektga maydon qo'shildi va kimdir uni to'liq taqqoslayotgan edi
Oxirgisi bahsli, lekin amaliy qoida shunday: agar o'zgarish kimningdir ishlab turgan kodini buzishi mumkin bo'lsa, u buzuvchi.
Men bir necha marta "kichik tuzatish" deb chiqargan narsam kimningdir kodini buzganini ko'rganman. Endi shubha bo'lsa katta raqamni ko'taraman. Versiya raqami arzon, ishonch esa qimmat.
Eng ko'p vaqt oladigan narsa: issue'lar
Kod yozish paketni yuritishning kichik qismi. Asosiy vaqt — odamlar bilan muloqot.
Issue'lar taxminan uch turga bo'linadi.
Haqiqiy xatolar. Bular eng qadrli — kimdir sizga bepul sinov o'tkazib bergan. Lekin ular odatda takrorlash ma'lumotisiz keladi. Men issue shablonini qo'shdim va bu holatni sezilarli yaxshiladi: versiya, muhit, kutilgan va haqiqiy natija.
Ishlatish savollari. "Buni qanday qilaman?" Bu odatda hujjat kamchiligini bildiradi. Javob berganda men javobni README'ga ham qo'shaman — shunda savol ikkinchi marta kelmaydi.
Yangi qobiliyat so'rovlari. Eng qiyin turi, chunki bu yerda "yo'q" deyish kerak bo'ladi.
"Yo'q" deyishni o'rganish
Bu men uchun eng qiyin qismi bo'ldi.
Kimdir sizning paketingizni ishlatyapti va biror narsa so'rayapti. Rad etish noqulay. Lekin har bir qo'shilgan qobiliyat — bu abadiy majburiyat: uni qo'llab-quvvatlash, sinash, hujjatlashtirish va u bilan mos kelmaydigan o'zgarishlardan qochish kerak.
Mening mezonim shunday: so'rov paketning asosiy vazifasiga tegishlimi?
Agar ha — muhokama qilamiz. Agar yo'q — halol aytaman: bu paketning qamrovidan tashqarida, lekin siz uni shu tarzda o'zingiz qila olasiz.
Bu javob odamlarga ham foydali. Noaniq "ko'rib chiqaman" degan javob ularni kutishga majbur qiladi. Aniq "yo'q" esa ularga boshqa yechim izlash imkonini beradi.
Qamrovni README'da yozib qo'yish yaxshi ishlaydi: bu paket nima qiladi va nima qilmaydi. Ikkinchi ro'yxat birinchisidan kam foydali emas.
Charchash haqida halol gap
Ochiq kodli paketni yuritish ko'ngilli ish, lekin u majburiyatga o'xshab tuyula boshlaydi.
Issue ochilgan, siz javob bermagansiz, va bu sizning ustingizda osilib turadi. Bir necha oydan keyin siz repositoriyni ochishdan qochasiz.
Men uchta narsa yordam berishini ko'rdim.
Kutilmalarni yozib qo'ying. README'da bitta jumla yetadi: bu paket shaxsiy vaqtda yuritiladi, javoblar kechikishi mumkin. Bu halol va u bosimni kamaytiradi.
Paketni tugagan deb e'lon qiling. Har bir kod doimiy o'sishi shart emas. Agar paket o'z vazifasini bajarayotgan bo'lsa, u "barqaror va tugallangan" bo'lishi mumkin. Bu tashlab qo'yish emas — bu holat.
Tashlab qo'yish kerak bo'lsa, buni ayting. Eng yomon variant — jimgina yo'qolish. Agar paketni yuritmaydigan bo'lsangiz, README'da yozing. Odamlar rejalashtira oladi, kimdir uni o'z qo'liga olishi ham mumkin.
Arziydimi
Ha, lekin sabab kutilganidan boshqacha.
Ochiq kod sizga shuhrat keltirmaydi va ish taklifi ham kamdan-kam. Real qaytim boshqa joyda.
Birinchisi — kod sifati o'zgaradi. Boshqa odamlar o'qiydigan va ishlatadigan kodni yozganda siz nomlarga, hujjatga va chegara holatlariga butunlay boshqacha e'tibor berasiz. Bu odat keyin ish kodingizga ham o'tadi.
Ikkinchisi — siz o'z taxminlaringizni ko'rasiz. Sizga aniq tuyulgan narsa boshqa odam uchun umuman aniq emas ekanini bilib olasiz. Bu API dizayni haqida hech qanday kitob bermaydigan bilim.
Agar paket chiqarishni o'ylayotgan bo'lsangiz, maslahatim oddiy: qamrovni kichik qiling. Bitta ishni yaxshi bajaradigan paketni yillar davomida yuritish mumkin. Hamma narsani qiladigan paket sizni olti oyda charchatadi.