Hujjat o'qish: MDN, README va changelog — rasmiy manbadan tez javob topish

Qisqacha: Rasmiy hujjat (documentation) — texnologiyani yaratganlar yozgan eng ishonchli manba. U kitobdek boshidan oxirigacha o'qilmaydi: kerakli bo'limga to'g'ridan-to'g'ri sakraladi. MDN sahifasida avval Syntax, Return value va Examples o'qiladi; paket uchun — README; versiya yangilashdan oldin — CHANGELOG.

Bu darsda

• Guide (qo'llanma) va Reference (ma'lumotnoma) farqini tushuntira olasiz.
• MDN sahifasining bo'limlarini tanib, 60 soniyada kerakli javobni topa olasiz.
• npm paket sahifasi va README'dan paketni o'rnatish va ishlatishni o'qiy olasiz.
• CHANGELOG'dan versiya yangilashda nima buzilishi mumkinligini aniqlay olasiz.
• GitHub issues va spetsifikatsiya qachon kerak bo'lishini bilasiz.

Oldin bilishingiz kerak: Samarali qidirish (googling), Veb standartlari va brauzer mosligi, npm'ga birinchi qadam, Markdown.

1. Nega bu kerak?

Jasur 2021-yilgi video darslikni ko'rib, undagi buyruqni takrorladi. Buyruq ishlamadi. Sababi oddiy: dastur o'shandan beri uch marta yangilangan, video esa o'zgarmagan.

Video, blog va maqola — birovning qayta hikoyasi. Ular eskiradi. Texnologiyani yaratganlar esa o'z hujjatini har versiyada yangilab boradi. Shuning uchun dasturchining eng ishonchli manbasi — rasmiy hujjat (documentation), qisqacha "docs".

Ko'p boshlovchi hujjatdan qo'rqadi: uzun, inglizcha, quruq. Lekin hujjat roman emas. Uni birinchi sahifadan oxirigacha o'qish shart emas.

O'xshatish: ingliz-o'zbek lug'ati. Lug'atni hech kim boshidan oxirigacha o'qimaydi. Kerakli so'zni ochasiz, ma'nosini ko'rasiz, yopasiz. Hujjat ham shunday — faqat uning "alifbosini", ya'ni tuzilishini bilish kerak. Bu dars aynan shu haqida.

2. Hujjat turlari: Guide va Reference

2.1 Ikki xil maqsad

Deyarli har bir texnologiya hujjati ikki qismdan iborat:

API (Application Programming Interface) — dastur boshqa dasturlarga taqdim qiladigan buyruqlar to'plami. Masalan, console.log — JavaScript'ning API'si. "API reference" — shu buyruqlarning ma'lumotnomasi.

Misollar:

• MDN: "Learn web development" — guide; "Reference" bo'limi — ma'lumotnoma.
• Node.js: nodejs.org/en/learn — guide; nodejs.org/docs/latest/api — API ma'lumotnomasi.

2.2 Qaysi biridan boshlash kerak?

Qoida sodda: mavzu yangi bo'lsa — guide, aniq savol bo'lsa — reference.

Birinchi marta Node.js bilan tanishganingizda API ro'yxatini ochsangiz, yuzlab notanish nomni ko'rib adashasiz. Aksincha, "console.log bir nechta qiymat qabul qiladimi?" degan aniq savolga guide'dan javob izlash — sekin.

Tekshirib ko'ring: Siz ertaga CSS'ni noldan boshlaysiz. Hujjatning qaysi turini ochasiz?

3. MDN sahifasining tuzilishi

MDN Web Docs (developer.mozilla.org) — HTML, CSS va JavaScript bo'yicha eng mashhur ma'lumotnoma. Uni veb standartlari darsida tilga olgan edik. Uning reference sahifalari hammasi bir xil qolipda. Qolipni bir marta o'rgansangiz, minglab sahifani tez o'qiysiz.

3.1 Bo'limlar tartibi

Math.round() sahifasini misol qilib olamiz. Math.round — sonni eng yaqin butun songa yaxlitlaydigan tayyor JavaScript metodi. Metod — biror narsaga "biriktirilgan" tayyor buyruq; console.log ham metod: u console ga biriktirilgan.

Sahifa bo'limlari tepadan pastga:

3.2 To'liq yechilgan misol: Math.round()

Syntax bo'limida:

Math.round(x)

Bu yerda x — siz beradigan qiymat uchun "joy egallovchi" nom. Uning o'rniga haqiqiy son yoziladi: Math.round(4.7).

Parameters bo'limida x haqida bir qator: A number. — "son".

Return value bo'limida: The value of x rounded to the nearest integer. — "x ning eng yaqin butun songa yaxlitlangan qiymati". integer — butun son.

Endi o'qiganimizni tekshiramiz. Bu kodni fayl qilib node bilan ishga tushiring yoki Node REPL'ga (Node.js darsida o'rgangan edingiz) yozing:

console.log(Math.round(4.7)); // 5
console.log(Math.round(4.2)); // 4
console.log(Math.round(2.5)); // 3

Hammasi kutilgandek. Endi qiziq holat:

console.log(Math.round(-5.5)); // -5

Kutgandingizmi? Ko'pchilik -6 deb o'ylaydi. Javob Description bo'limida: kasr qismi aynan 0.5 bo'lsa, son "musbat cheksizlik tomonga", ya'ni kattarog'iga yaxlitlanadi. −5 soni −6 dan katta. Shuning uchun -5.

Hujjat sizni kutilmagan natijadan oldindan ogohlantirdi. Blogda bunday detal ko'pincha tushib qoladi.

3.3 Syntax'dagi maxsus belgilar

console.log() sahifasidagi Syntax boshqacharoq ko'rinadi:

console.log(val1)
console.log(val1, /* …, */ valN)

• Bir nechta qator — metodni bir necha xil usulda yozish mumkin degani.
• /* …, */ — "bu yerda yana qancha xohlasangiz, qiymat bo'lishi mumkin". valN — "N-qiymat", ya'ni oxirgisi.

Demak, console.log("Narx:", 5000, "so'm") — to'g'ri: uchta qiymat berilgan.

Ba'zi parametrlar yonida Optional (ixtiyoriy) so'zi bo'ladi. Uni bermasangiz ham metod ishlaydi — standart qiymat ishlatiladi.

3.4 Brauzer mosligi va spetsifikatsiya

• Baseline: Widely available — "keng tarqalgan": barcha asosiy brauzerlarda uzoq vaqtdan beri ishlaydi. Math.round va console.log shunday.
• Browser compatibility jadvalida har brauzer uchun yashil (ishlaydi) yoki qizil (ishlamaydi) katak va versiya raqami bor. Yangi imkoniyatni ishlatishdan oldin shu jadvalga qarang.
• Specifications — rasmiy standart hujjatiga havola. Spetsifikatsiya (specification) — til yoki texnologiya qanday ishlashi kerakligini aniq belgilaydigan rasmiy qoidalar kitobi. JavaScript uchun u ECMAScript deb ataladi. U juda og'ir tilda yozilgan — boshlovchiga kerak emas. MDN uni sodda qilib tushuntirib beradi.

3.5 O'zingiz to'ldiring

MDN'dagi console.log() sahifasini oching. Return value bo'limida None (undefined) deb yozilgan. undefined — JavaScript'da "qiymat yo'q" degan maxsus qiymat.

Savol: console.log ekranga yozadi, lekin natija sifatida qaytaradi.

Maslahat: MDN sahifasini 60 soniyada o'qish tartibi: 1) Syntax — qanday yoziladi; 2) Return value — nima qaytadi; 3) Examples — misol; 4) kerak bo'lsa Description — maxsus holatlar. Browser compatibility'ga yangi imkoniyat ishlatayotganda qarang.

Tekshirib ko'ring: Math.round(-2.5) nima qaytaradi? Hujjatdagi qoidaga tayanib javob bering, keyin Node'da tekshiring.

4. npm paket sahifasi va README

4.1 npm sahifasi

npm darsida picocolors paketini ko'rgan edik. Har bir paketning npmjs.com/package/<nomi> manzilida sahifasi bor. O'ng tomonda paketning "pasporti":

Tepada tablar bor: Readme, Code, Dependencies (bu paket nimalarga bog'liq), Dependents (unga kimlar bog'liq), Versions (barcha versiyalar tarixi).

Terminaldan ham tez ko'rish mumkin:

npm view picocolors version license

Terminalda:

version = '1.1.1'
license = 'ISC'

Litsenziya (license) — muallif kodidan qanday foydalanishga ruxsat bergani haqidagi shartnoma. MIT, ISC, Apache-2.0 — "erkin" litsenziyalar: tijoriy loyihada ham bemalol ishlatish mumkin, faqat muallif nomini saqlash kerak.

4.2 Paket "sog'lom"mi?

Paket tanlashda uchta belgiga qarang:

1. Mashhurlik — haftalik yuklab olishlar ko'p (minglab yoki millionlab).
2. Tiriklik — oxirgi yangilanish juda eski emas, muammolarga javob berilyapti.
3. Litsenziya — sizning maqsadingizga mos.

Kichik, barqaror paket ko'p yillar yangilanmasligi mumkin — bu har doim ham yomon emas. Lekin 5 yil yangilanmagan va ko'p muammosi javobsiz qolgan paketdan ehtiyot bo'ling. Paket xavfsizligini kengaytmalar darsidagi kabi mezonlar bilan tekshirasiz: kim yozgan, qancha odam ishlatadi.

4.3 README tuzilishi

README — "meni o'qi" degani. Loyihaning bosh sahifasi, u Markdown'da (README.md) yoziladi. Odatda shunday bo'limlari bor:

# nomi

Bir-ikki gapda: paket nima qiladi.

## Installation
npm install nomi

## Usage
Eng qisqa ishlatish misoli (3–10 qator).

## API / Options
Har bir metod va sozlama tavsifi.

## Contributing
Loyihaga qanday yordam berish mumkin.

## License
MIT

README'ni o'qish tartibi: avval birinchi gap (menga shu kerakmi?), keyin Installation va Usage. Qolganini — kerak bo'lganda.

Sarlavha ostida ko'pincha kichik rangli "nishonlar" (badges) turadi: versiya, yuklab olishlar, testlar holati. Ular sahifadagi ma'lumotning qisqa ko'rinishi.

Tekshirib ko'ring: Siz yangi paketni loyihaga qo'shmoqchisiz. README'ning qaysi ikki bo'limini birinchi o'qiysiz?

5. CHANGELOG: nima o'zgargan?

5.1 Nega kerak?

npm darsida SemVer'ni o'rgangan edingiz: MAJOR.MINOR.PATCH. Birinchi raqam (MAJOR) o'zgarsa — eski kod buzilishi mumkin. Lekin aynan nima buziladi? Javob — CHANGELOG (o'zgarishlar jurnali) faylida.

CHANGELOG.md — har versiyada nima qo'shilgani, o'zgargani va tuzatilgani yozilgan fayl. GitHub'da xuddi shu ma'lumot ko'pincha Releases (relizlar) bo'limida ham bo'ladi.

5.2 Qanday o'qiladi

Ko'p loyihalar "Keep a Changelog" degan umumiy qolipda yozadi:

## [3.0.0] - 2026-05-10
### Removed
- `colorize()` olib tashlandi. O'rniga `paint()` ishlating.
### Changed
- BREAKING: Node.js 18 endi qo'llab-quvvatlanmaydi.

## [2.5.0] - 2026-02-01
### Added
- Yangi `bold()` funksiyasi.
### Fixed
- Windows terminalida rang chiqmasligi tuzatildi.

Bu yerda:

• Added — qo'shildi, Changed — o'zgardi, Removed — olib tashlandi, Fixed — tuzatildi.
• Deprecated — eskirgan deb belgilandi (hali ishlaydi, lekin keyingi versiyalarda olib tashlanadi).
• Security — xavfsizlik tuzatishi. Bunday versiyaga imkon qadar tez o'tish kerak.
• BREAKING yoki Breaking changes — "buzuvchi o'zgarish": eski kodingiz ishlamay qolishi mumkin.

Katta yangilanishlarda ko'pincha alohida Migration guide (o'tish qo'llanmasi) bo'ladi. U eski koddan yangisiga qadamma-qadam o'tishni ko'rsatadi.

Tekshirib ko'ring: Yuqoridagi CHANGELOG bo'yicha: loyihangizda colorize() ishlatilgan. 2.5.0 dan 3.0.0 ga o'tsangiz nima bo'ladi va nima qilish kerak?

6. GitHub issues: boshqalar ham shu xatoga uchraganmi?

GitHub — dasturchilar kodini saqlaydigan sayt, uni 07-qismda o'rganamiz. Har bir loyihaning GitHub sahifasida Issues (muammolar) bo'limi bor. U yerda foydalanuvchilar topgan xatolar va takliflar muhokama qilinadi.

Qachon kerak bo'ladi? Kutubxonada g'alati xato chiqdi, Stack Overflow'da javob yo'q. Ehtimol, bu yangi xato va u haqida boshqalar allaqachon Issues'ga yozgan.

Qanday o'qiladi:

• Open (ochiq) — muammo hali hal qilinmagan. Closed (yopiq) — hal qilingan yoki rad etilgan.
• Qidiruv maydoniga xato matnini yozing — yopiq muammolar ham ko'rinsin.
• Uzun muhokamada workaround (vaqtinchalik aylanma yechim) degan so'zni qidiring — rasmiy tuzatish chiqquncha ishlatiladigan yo'l.

Diqqat: Issues — xato haqida xabar berish joyi, "menga o'rgating" joyi emas. Yangi issue yozishdan oldin albatta qidiring: xuddi shu muammo 50 marta yozilgan bo'lishi mumkin.

Qaysi savolga qaysi hujjat:

flowchart TD
    S[Savolim bor] --> A{Qanday savol?}
    A -- Yangi mavzu --> G[Guide / Learn]
    A -- Aniq metod yoki buyruq --> R[Reference]
    A -- Paketni ishlatish --> M[README]
    A -- Versiyani yangilash --> C[CHANGELOG / Releases]
    A -- Kutubxonadagi xato --> I[GitHub Issues]

7. Ko'p uchraydigan xatolar

7.1 Hujjatni kitobdek boshidan o'qish

Butun reference'ni ketma-ket o'qib, charchab, tashlab ketish.

Aniq savol bilan kiring va kerakli bo'limga sakrang: Syntax, Return value, Examples.

7.2 Return value'ni o'qimaslik

Metod nima qaytarishini taxmin qilish. Masalan, "console.log natija sifatida matnni qaytaradi" deb o'ylash.

Return value bo'limiga qarang: console.log hech narsa qaytarmaydi (undefined). Bu JavaScript qismida muhim bo'ladi.

7.3 CHANGELOG'siz MAJOR yangilash

2.x dan 3.0.0 ga o'ylamasdan o'tish — loyiha ishlamay qoladi.

Avval CHANGELOG'dagi Removed, Changed va BREAKING qismlarini o'qing, bo'lsa — Migration guide'ni.

7.4 Eski versiya hujjatini o'qish

Qidiruvdan eski versiya hujjatiga tushib qolish (manzilda /v2/ yoki /docs/v14/ kabi qism bor).

Sahifadagi versiya tanlagichni tekshiring va o'zingizdagi versiyaga moslang (package.json dagi versiya yoki node --version orqali bilasiz).

8. Mashqlar

1-mashq (oson)

MDN'da Math.round() sahifasini oching (qidiruv: site:developer.mozilla.org Math.round). Quyidagilar nima qaytarishini avval hujjat bo'yicha taxmin qiling, keyin Node'da tekshiring: Math.round(0.5), Math.round(-0.5), Math.round(9.49).

Ishora: Description bo'limidagi "aynan 0.5" qoidasi 3.2-bob.

console.log(Math.round(0.5)); // 1
console.log(Math.round(-0.5)); // -0
console.log(Math.round(9.49)); // 9

2-mashq (o'rta)

npmjs.com saytida picocolors paketini toping (yoki terminalda npm view ishlating). Uchta savolga javob bering: oxirgi versiyasi, litsenziyasi va bu litsenziya tijoriy loyihada ishlatishga ruxsat beradimi.

Ishora: 4.1 bo'limdagi jadval va npm view picocolors version license buyrug'i.

npm view picocolors version license

version = '1.1.1'
license = 'ISC'

3-mashq (qiyin)

Loyihangizda ranglar paketining 2.5.0 versiyasi bor. Kodingizda colorize() va bold() ishlatilgan, kompyuteringizda Node.js 24. 5.2 bo'limdagi CHANGELOG'ni o'qib, 3.0.0 ga o'tish rejasini yozing: nima buziladi, nima buzilmaydi, nima qilish kerak.

Ishora: har bir ### bo'lim sarlavhasini (Removed, Changed, Added) alohida tekshiring.

9. Real ishda

• Har kuni. Tajribali dasturchi kuniga bir necha marta MDN yoki kutubxona hujjatini ochadi. Hamma metodni yoddan bilish shart emas — tez topa olish muhim.
• Paket tanlash. Jamoada yangi kutubxona qo'shishdan oldin uning npm sahifasi, README'si va litsenziyasi tekshiriladi. Litsenziyaga mos kelmagan paket kompaniyaga huquqiy muammo keltirishi mumkin.
• Yangilash kuni. Paketlarni yangilash — muntazam ish. Tajribali dasturchi avval CHANGELOG'ni o'qiydi, keyin yangilaydi. npm outdated kabi buyruqlarni npm chuqur darsida o'rganamiz.
• Intervyu. "Yangi kutubxonani qanday o'rganasiz?" — "README va Getting Started'dan boshlayman, keyin API reference'dan kerakli qismni o'qiyman".

Xulosa

• Rasmiy hujjat — eng ishonchli manba; u lug'at kabi ishlatiladi, roman kabi o'qilmaydi.
• Guide — yangi mavzu uchun, Reference — aniq savol uchun.
• MDN sahifasi: Syntax → Parameters → Return value → Description → Examples → Browser compatibility; maxsus holatlar Description'da.
• npm sahifasi paketning pasporti: versiya, litsenziya, yuklab olishlar, oxirgi yangilanish; README'da — Installation va Usage.
• CHANGELOG versiyalar orasidagi farqni aytadi; MAJOR yangilashdan oldin Removed va BREAKING o'qiladi.
• Kutubxonadagi yangi xato — GitHub Issues'da, spetsifikatsiya esa kamdan-kam kerak.

Keyingi dars: Xato xabarini o'qish san'ati — xato turi, fayl:qator:ustun manzili va stack trace'ni o'qib, xato qayerdaligini bir qarashda topishni o'rganamiz.