19.5-dars: Semantik versiyalash

2.5.3
│ │ └── PATCH — xato tuzatishlar
│ └──── KICHIK — yangi imkoniyatlar
└────── ASOSIY — buzuvchi o'zgarishlar

1.0.0-alpha.1     # alpha — erta, beqaror
1.0.0-beta.1      # beta — funksiyalar to'liq, sinovda
1.0.0-rc.1        # rc (release candidate) — deyarli tayyor
1.0.0             # barqaror (stable)

# src/wisar/__init__.py
__version__ = "1.2.3"

# pyproject.toml
dynamic = ["version"]
[tool.hatch.version]
path = "src/wisar/__init__.py"    # __version__ dan oladi (19.2)

# O'zgarishlar

## [1.3.0] - 2026-09-17
### Qo'shildi
- Yangi `export_csv` funksiyasi

## [1.2.4] - 2026-09-10
### Tuzatildi
- `hisobla` da nolga bo'lish xatosi

ASOSIY.KICHIK.PATCH  (masalan 2.5.3)
  MAJOR — buzuvchi o'zgarish (2.0.0)
  MINOR — yangi imkoniyat (1.3.0)
  PATCH — xato tuzatish (1.2.4)

pre-release: 1.0.0-alpha.1 < beta.1 < rc.1 < 1.0.0
0.x.y — barqaror emas; 1.0.0 — barqaror API

# versiya bir joyda:
__version__ = "1.2.3"   # __init__.py
# pyproject.toml: dynamic = ["version"]

buzuvchi → major; yangi → minor; tuzatish → patch
quyi raqam oshsa, pastdagilar nolga
0.x — barqaror emas; 1.0.0 — API barqaror
pre-release: alpha < beta < rc < stable
versiyani bir joyda (dinamik)
CHANGELOG bilan o'zgarishlarni hujjatlang
SemVer — shartnoma, buzmang

"""ASOSIY.KICHIK.PATCH; qaysi o'zgarishga qaysi raqam; quyi raqam oshsa pastdagilar nolga; versiya taqqoslash."""

from packaging.version import Version


def keyingi_versiya(joriy: str, ozgarish: str) -> str:
    v = Version(joriy)
    asosiy, kichik, patch = v.major, v.minor, v.micro
    if ozgarish == "major":
        return f"{asosiy + 1}.0.0"          # pastdagilar nolga
    if ozgarish == "minor":
        return f"{asosiy}.{kichik + 1}.0"    # patch nolga
    if ozgarish == "patch":
        return f"{asosiy}.{kichik}.{patch + 1}"
    raise ValueError(ozgarish)


def main() -> None:
    print("=== 1. Versiya tuzilishi ===")
    v = Version("2.5.3")
    print(f"  2.5.3 → ASOSIY={v.major}, KICHIK={v.minor}, PATCH={v.micro}")

    print("\n=== 2. Keyingi versiya (o'zgarish turiga qarab) ===")
    joriy = "1.2.3"
    for ozgarish, izoh in [("patch", "xato tuzatish"), ("minor", "yangi imkoniyat"), ("major", "buzuvchi o'zgarish")]:
        yangi = keyingi_versiya(joriy, ozgarish)
        print(f"  {joriy} + {ozgarish:6} ({izoh:18}) → {yangi}")

    print("\n=== 3. ⭐ Quyi raqam oshsa, pastdagilar nolga ===")
    print(f"  1.2.3 minor → {keyingi_versiya('1.2.3', 'minor')}  (patch nolga)")
    print(f"  1.2.3 major → {keyingi_versiya('1.2.3', 'major')}  (minor va patch nolga)")

    print("\n=== 4. Versiya taqqoslash ===")
    print(f"  2.0.0 > 1.9.9: {Version('2.0.0') > Version('1.9.9')}")
    print(f"  1.10.0 > 1.9.0: {Version('1.10.0') > Version('1.9.0')}  (10 > 9, satr emas)")
    print(f"  1.2.3 == 1.2.3: {Version('1.2.3') == Version('1.2.3')}")


if __name__ == "__main__":
    main()

=== 1. Versiya tuzilishi ===
  2.5.3 → ASOSIY=2, KICHIK=5, PATCH=3

=== 2. Keyingi versiya (o'zgarish turiga qarab) ===
  1.2.3 + patch  (xato tuzatish     ) → 1.2.4
  1.2.3 + minor  (yangi imkoniyat   ) → 1.3.0
  1.2.3 + major  (buzuvchi o'zgarish) → 2.0.0

=== 3. ⭐ Quyi raqam oshsa, pastdagilar nolga ===
  1.2.3 minor → 1.3.0  (patch nolga)
  1.2.3 major → 2.0.0  (minor va patch nolga)

=== 4. Versiya taqqoslash ===
  2.0.0 > 1.9.9: True
  1.10.0 > 1.9.0: True  (10 > 9, satr emas)
  1.2.3 == 1.2.3: True

"""o'zgarish buzuvchimi (major) yoki qo'shuvchimi (minor) yoki tuzatuvchimi (patch); API o'zgarishlarini toifalash; to'g'ri versiya taklifi."""

from packaging.version import Version


def versiya_turi(ozgarish_turi: str) -> str:
    buzuvchi = {"funksiya_olib_tashlash", "nom_ozgartirish", "parametr_olib_tashlash", "qaytish_turi_ozgarish", "majburiy_parametr"}
    qoshuvchi = {"yangi_funksiya", "ixtiyoriy_parametr", "yangi_imkoniyat"}
    tuzatuvchi = {"xato_tuzatish", "hujjat", "ichki_refaktoring", "tezlik"}
    if ozgarish_turi in buzuvchi:
        return "major"
    if ozgarish_turi in qoshuvchi:
        return "minor"
    if ozgarish_turi in tuzatuvchi:
        return "patch"
    return "nomalum"


def main() -> None:
    print("=== 1. O'zgarishlarni toifalash ===")
    ozgarishlar = [
        ("xato_tuzatish", "hisobda nolga bo'lish tuzatildi"),
        ("yangi_funksiya", "export_csv qo'shildi"),
        ("funksiya_olib_tashlash", "eski salom() olib tashlandi"),
        ("ixtiyoriy_parametr", "format= ixtiyoriy parametr"),
        ("nom_ozgartirish", "hisobla → calculate"),
        ("hujjat", "README yaxshilandi"),
        ("majburiy_parametr", "yangi majburiy 'kalit' argument"),
    ]
    for tur, izoh in ozgarishlar:
        versiya = versiya_turi(tur)
        belgi = "🔴" if versiya == "major" else "🟡" if versiya == "minor" else "🟢"
        print(f"  {belgi} {versiya:6} — {izoh}")

    print("\n=== 2. Kalit savol ===")
    print("  'Bu o'zgarish mavjud foydalanuvchi kodini buzadimi?'")
    print("  Ha → major | Yo'q, yangi → minor | Yo'q, tuzatish → patch")

    print("\n=== 3. Misol: bir nechta o'zgarish ===")
    o_lar = ["xato_tuzatish", "yangi_funksiya", "funksiya_olib_tashlash"]
    turlar = [versiya_turi(o) for o in o_lar]
    # eng yuqori o'zgarish belgilaydi
    if "major" in turlar:
        yakuniy = "major"
    elif "minor" in turlar:
        yakuniy = "minor"
    else:
        yakuniy = "patch"
    print(f"  o'zgarishlar: {turlar}")
    print(f"  yakuniy versiya turi: {yakuniy} (eng yuqori o'zgarish belgilaydi)")
    print(f"  1.2.3 → {'2.0.0' if yakuniy == 'major' else '1.3.0' if yakuniy == 'minor' else '1.2.4'}")


if __name__ == "__main__":
    main()

=== 1. O'zgarishlarni toifalash ===
  🟢 patch  — hisobda nolga bo'lish tuzatildi
  🟡 minor  — export_csv qo'shildi
  🔴 major  — eski salom() olib tashlandi
  🟡 minor  — format= ixtiyoriy parametr
  🔴 major  — hisobla → calculate
  🟢 patch  — README yaxshilandi
  🔴 major  — yangi majburiy 'kalit' argument

=== 2. Kalit savol ===
  'Bu o'zgarish mavjud foydalanuvchi kodini buzadimi?'
  Ha → major | Yo'q, yangi → minor | Yo'q, tuzatish → patch

=== 3. Misol: bir nechta o'zgarish ===
  o'zgarishlar: ['patch', 'minor', 'major']
  yakuniy versiya turi: major (eng yuqori o'zgarish belgilaydi)
  1.2.3 → 2.0.0

"""pre-release: alpha < beta < rc < stable; tartib; --pre bilan o'rnatiladi; 0.x barqaror emas; 1.0.0 barqaror API."""

from packaging.version import Version


def main() -> None:
    print("=== 1. Pre-release tartibi ===")
    versiyalar = ["1.0.0a1", "1.0.0b1", "1.0.0rc1", "1.0.0"]
    saralangan = sorted(versiyalar, key=Version)
    print(f"  saralangan: {saralangan}")
    print(f"  1.0.0-alpha < 1.0.0-beta: {Version('1.0.0a1') < Version('1.0.0b1')}")
    print(f"  1.0.0-rc < 1.0.0 (barqaror): {Version('1.0.0rc1') < Version('1.0.0')}")

    print("\n=== 2. Pre-release turlari ===")
    turlar = [
        ("alpha (a)", "erta sinov, ko'p o'zgaradi"),
        ("beta (b)", "funksiyalar to'liq, xatolar bor"),
        ("rc (release candidate)", "chiqishga tayyor nomzod"),
        ("stable", "barqaror, tavsiya etiladi"),
    ]
    for tur, izoh in turlar:
        print(f"  {tur:24} — {izoh}")

    print("\n=== 3. Pre-release aniqlash ===")
    for v_str in ["1.0.0a1", "1.0.0", "2.1.0rc2"]:
        v = Version(v_str)
        print(f"  {v_str}: pre-release={v.is_prerelease}")
    print("  ⭐ pre-release pip da sukut o'rnatilmaydi (--pre kerak)")

    print("\n=== 4. 0.x vs 1.0.0 ===")
    print(f"  0.5.0: barqaror emas (API o'zgarishi mumkin)")
    print(f"  1.0.0: birinchi barqaror API (SemVer to'liq kuchga kiradi)")
    print(f"  0.5.0 < 1.0.0: {Version('0.5.0') < Version('1.0.0')}")
    print("  ⚠️ 0.x da har o'zgarish buzuvchi bo'lishi mumkin")


if __name__ == "__main__":
    main()

=== 1. Pre-release tartibi ===
  saralangan: ['1.0.0a1', '1.0.0b1', '1.0.0rc1', '1.0.0']
  1.0.0-alpha < 1.0.0-beta: True
  1.0.0-rc < 1.0.0 (barqaror): True

=== 2. Pre-release turlari ===
  alpha (a)                — erta sinov, ko'p o'zgaradi
  beta (b)                 — funksiyalar to'liq, xatolar bor
  rc (release candidate)   — chiqishga tayyor nomzod
  stable                   — barqaror, tavsiya etiladi

=== 3. Pre-release aniqlash ===
  1.0.0a1: pre-release=True
  1.0.0: pre-release=False
  2.1.0rc2: pre-release=True
  ⭐ pre-release pip da sukut o'rnatilmaydi (--pre kerak)

=== 4. 0.x vs 1.0.0 ===
  0.5.0: barqaror emas (API o'zgarishi mumkin)
  1.0.0: birinchi barqaror API (SemVer to'liq kuchga kiradi)
  0.5.0 < 1.0.0: True
  ⚠️ 0.x da har o'zgarish buzuvchi bo'lishi mumkin

"""versiya boshqaruvi: o'zgarishlardan versiya turini aniqlash, keyingi versiyani hisoblash, __init__.py yangilash, CHANGELOG yozuvi; to'liq oqim."""

import re
from packaging.version import Version


def versiya_turi(o_lar: list[str]) -> str:
    if any(o["tur"] == "buzuvchi" for o in o_lar):
        return "major"
    if any(o["tur"] == "qoshildi" for o in o_lar):
        return "minor"
    return "patch"


def keyingi(joriy: str, tur: str) -> str:
    v = Version(joriy)
    if tur == "major":
        return f"{v.major + 1}.0.0"
    if tur == "minor":
        return f"{v.major}.{v.minor + 1}.0"
    return f"{v.major}.{v.minor}.{v.micro + 1}"


def changelog_yoz(versiya: str, sana: str, o_lar: list[str]) -> str:
    guruhlar = {"qoshildi": "Qo'shildi", "buzuvchi": "O'zgardi (buzuvchi)", "tuzatildi": "Tuzatildi"}
    satrlar = [f"## [{versiya}] - {sana}"]
    for kalit, sarlavha in guruhlar.items():
        tegishli = [o["matn"] for o in o_lar if o["tur"] == kalit]
        if tegishli:
            satrlar.append(f"### {sarlavha}")
            satrlar.extend(f"- {m}" for m in tegishli)
    return "\n".join(satrlar)


def main() -> None:
    joriy = "1.2.3"
    ozgarishlar = [
        {"tur": "tuzatildi", "matn": "hisobla() da nolga bo'lish xatosi"},
        {"tur": "qoshildi", "matn": "export_csv() funksiyasi"},
    ]

    print("=== 1. O'zgarishlar ===")
    for o in ozgarishlar:
        print(f"  [{o['tur']}] {o['matn']}")

    print("\n=== 2. Keyingi versiya ===")
    tur = versiya_turi(ozgarishlar)
    yangi = keyingi(joriy, tur)
    print(f"  joriy: {joriy}")
    print(f"  o'zgarish turi: {tur} (yangi imkoniyat bor → minor)")
    print(f"  keyingi versiya: {yangi}")

    print("\n=== 3. __init__.py yangilash ===")
    init_matn = f'__version__ = "{joriy}"\n'
    yangi_matn = re.sub(r'__version__ = "[^"]+"', f'__version__ = "{yangi}"', init_matn)
    print(f"  oldin: {init_matn.strip()}")
    print(f"  keyin: {yangi_matn.strip()}")

    print("\n=== 4. CHANGELOG yozuvi ===")
    changelog = changelog_yoz(yangi, "2026-09-17", ozgarishlar)
    for qator in changelog.splitlines():
        print(f"  {qator}")
    print("  ⭐ versiya + CHANGELOG — har chiqishda birga yangilanadi")


if __name__ == "__main__":
    main()

=== 1. O'zgarishlar ===
  [tuzatildi] hisobla() da nolga bo'lish xatosi
  [qoshildi] export_csv() funksiyasi

=== 2. Keyingi versiya ===
  joriy: 1.2.3
  o'zgarish turi: minor (yangi imkoniyat bor → minor)
  keyingi versiya: 1.3.0

=== 3. __init__.py yangilash ===
  oldin: __version__ = "1.2.3"
  keyin: __version__ = "1.3.0"

=== 4. CHANGELOG yozuvi ===
  ## [1.3.0] - 2026-09-17
  ### Qo'shildi
  - export_csv() funksiyasi
  ### Tuzatildi
  - hisobla() da nolga bo'lish xatosi
  ⭐ versiya + CHANGELOG — har chiqishda birga yangilanadi

funksiya nomini o'zgartirib 1.2.4         # ❌ foydalanuvchi kodi buziladi
funksiya nomini o'zgartirib 2.0.0         # ✅ major

yangi funksiya qo'shib 2.0.0              # ❌ foydalanuvchi qo'rqadi
yangi funksiya qo'shib 1.3.0              # ✅ minor

1.2.3 → 1.3.3 (minor)                     # ❌ patch nolga tushmadi
1.2.3 → 1.3.0                             # ✅

__version__ = "1.2.3"  # va pyproject da ham   # ❌ takror
dynamic = ["version"]                     # ✅ bir joyda

0.2.0 barqaror API deb ishlatish          # ⚠️ 0.x o'zgaradi
# ✅ 1.0.0 ga chiqqach barqaror

versiya chiqarib, nima o'zgarganini yozmaslik   # ❌
# ✅ CHANGELOG.md yangilang

1.2.0 dan keyin 1.1.0                     # ❌ mumkin emas
# ✅ versiya doim o'sib borishi kerak

1.  xato tuzatildi
2.  yangi funksiya qo'shildi
3.  funksiya nomi o'zgartirildi
4.  ixtiyoriy parametr qo'shildi
5.  README yaxshilandi
6.  parametr olib tashlandi
7.  ichki refaktoring (API o'zgarmadi)
8.  yangi funksiya + xato tuzatish (birga)

1.  # funksiya olib tashlandi
    1.2.3 → 1.2.4

2.  # yangi funksiya qo'shildi
    1.2.3 → 2.0.0

3.  # minor oshirish
    1.2.3 → 1.3.3

4.  # versiya kamaytirish
    1.5.0 → 1.4.0

5.  # 0.x ni barqaror deb ishlatish
    "0.3.0 API barqaror"