Sémantické verzování

Moduly npm používají semantické verzování, které přesně říká, jak má být verze modulu specifikovaná a kdy se má změnit. Označení verze se skládá ze tří částí:

• major
• minor
• patch

Máme-li např. číslo verze 4.3.1, pak 4 je major, 3 je minor a 1 je patch část. Major se povinně mění tehdy, když dojde k zpětně nekompatibilním zásahům. Minor se změní, pokud je přidána nová funkcionalita, která však musí být zpětně kompatibilní v aktuální major verzi. A konečně patch verze se mění jen tehdy, když dojde k zpětně kompatibilním opravám chyb. Tohle pravidlo neplatí jen tehdy, je-li major verze 0, pak mohou vznikat nekompatibility i mezi jednotlivými minor a patch verzemi.

Uvedení verze v package.json

Protože se moduly neustále vyvíjí a opravují se jejich chyby, mění se i neustále jejich verze. Abychom nemuseli neustále přepisovat novou verzi v package.json, používají se v něm zápisy verzí, které jsou prefixovány znaky ^ a ~. První znak říká, že požadujeme, aby byla major verze stejná, druhý znak dělá to samé pro minor verzi. Několik příkladů jistě pomůže (zápis verze z package.json):

~4.3.1

• >= 4.3.1 < 4.4.0
• min. požadovaná verze je 4.3.1 a každá vyšší, s major 4 a minor 3

^4.3.1

• >= 4.3.1 < 5.0.0
• min. požadovaná verze je také 4.3.1, ale platí i pro minor vyšší než 3

Jiná pravidla platí pro verzi začínající 0, zde mají oba znaky stejný význam:

^0.3.1 i ~0.3.1

• >= 0.3.1 < 0.4.0

A ještě jinak je to ve chvíli, kdy je major i minor verze 0:

^0.0.2

• = 0.0.2, platí tedy pouze pro uvedenou verzi

~0.0.2

• >= 0.0.2 < 0.1.0, patch verze se může měnit

Protože npm ve výchozím stavu zapisuje znak ^ jako prefix verze (pokud zadáte příkaz npm install --save nazev-modulu), doporučuji se vždy ujistit, zda je daný modul vyvíjen kvalitním vývojářem, který daná pravidla skutečně dodržuje. Stává se, že tomu tak není a objeví se zpětně nekompatibilní změna v nové minor verzi (je dobré projít si starší issues na Githubu). V takovém případě je lepší zápis verze prefixovaný znakem ^ nepoužívat a raději použít zápis se znakem ~, případně specifikovat přesnou verzi.

Absence verze závislého modulu

Speciálním extrémem je absence specifikace verze, na které je modul závislý. Pokud je místo verze prázdný řádek nebo hvězdička, znamená to, že jakákoliv publikovaná verze je akceptovaná, všechny minulé i budoucí. To znamená, že když se API závislého modulu změní, může se celá aplikace sesypat.

Myslíte si, že jde o výjimečnou situaci? Tak třeba oficiální klient pro nejpopulárnější zápisník Evernote má v package.json verzi modulu oauth nespecifikovanou, a to dokonce v situaci, kdy modul oauth není ani v první verzi. Pokud zítra vyjde jeho nová nekompatibilní verze, aplikace využívající Evernote API mohou přestat fungovat.

Pokud jde konkrétně o Evernote, tak podobně neuvádí verze ani u příkladů, které tak nyní nefungují. Můžete si schválně zkusit Express sample aplikaci nainstalovat a spustit. Nejprve nepůjde příklad spustit kvůli novější verzi less-middleware. Až přijdete na to, jakou verzi autoři používali, spadne vám příklad na novější verzi frameworku express. A až nainstalujete tady správnou verzi, spadne vám příklad na nekompatibilitě s modulem jade.

Závěr

V package.json uvádějte verze modulů, na kterých je vyvíjený modul závislý. Verzi neuvádějte jen tehdy, pokud proto máte opravdu dobrý důvod. Pokud něco publikujete veřejně a chcete, aby to lidé používali, uvádějte verzi vždy.

Za review článku děkuji Pavlu Langovi.