diff --git a/docs/en-US/panel/gallery-addons.md b/docs/en-US/panel/gallery-addons.md index 1d91b52..7bfc321 100644 --- a/docs/en-US/panel/gallery-addons.md +++ b/docs/en-US/panel/gallery-addons.md @@ -19,6 +19,7 @@ Here is a proposal for a clear and aesthetic **table of contents** in the style - 2.2 [🔢 Versioning and semver](#semver) - 2.3 [📎 Dependency selection](#depends_on) - 2.4 [⚙️ Version operators: `^`, `~`, `=`](#selectors) + - 2.5 [✅ How to create version ranges without surprises?](#ranges_best_practices) 3. [🧪 Advanced options](#advanced) - 3.1 [🧩 Custom dependencies and tags](#advanced) @@ -167,6 +168,8 @@ Check the required dependencies if your package needs them. By default, we will - `Require paper=1.21.5` – requires package `paper` in exactly version `1.21.5` - `No requirements` – your package has no dependencies and can operate standalone +> **Recommendation:** When selecting dependencies, pick names like `paper-api` rather than the package names themselves like `paper`. Why? We explain it in the [How to create version ranges without surprises?](#ranges_best_practices) section. + #### Automatic Dependency Installation Some packages, like Paper, may require Java, which will be installed on the user's server. @@ -222,6 +225,54 @@ Knowing this theory, we can create the following version requirements: For more information, see [documentation](https://github.com/Masterminds/semver?tab=readme-ov-file#caret-range-comparisons-major) +--- + +### ✅ How to create version ranges without surprises? + + + +Two simple rules that make sure the user's server gets exactly the version you expect. + +#### 1. Pick names ending with `-api` (e.g., `paper-api`), not package names (e.g., `paper`) + +When creating a dependency, pick names like `paper-api`, `purpur-api`, or `minecraft-java-server` instead of the package names themselves (`paper`, `purpur`). These are the so-called `provides` names — the engine package "exposes" them together with its game version. + +**Why does it matter?** Versions of packages like `paper` have an extra number after a hyphen at the end, e.g., `1.20.6-151` (this is the number of a specific Paper release). The system that compares versions treats everything after the hyphen as a "preview version" — meaning it considers `1.20.6-151` to be **earlier (lower)** than `1.20.6`. Sounds strange, but that's how the versioning standard works. Because of this, a range can include versions you never intended. + +**Example:** + +Let's say your package works on versions from `1.20.1` to `1.20.5`, so you create a "lower than 1.20.6" range: + +``` +paper>=1.20.1-0 <1.20.6 +``` + +Unfortunately, version `1.20.6-151` fits inside this range — the system considers it lower than `1.20.6`. As a result, the user may end up with e.g. `paper=1.20.6-22` installed — exactly the version you wanted to exclude! + +Names like `paper-api` have no number after a hyphen (the package simply exposes `paper-api=1.20.6`), so the range works exactly as you expect: + +``` +paper-api>=1.20.1 <1.20.6 +``` + +#### 2. Write range bounds as "up to and including" (`>=` and `<=`), not "lower/greater than" (`<` and `>`) + +Instead of writing "lower than 1.20.6" (`<1.20.6`), say directly "at most 1.20.5" (`<=1.20.5`). So instead of: + +``` +paper>=1.20.1-0 <1.20.6 ❌ +``` + +write: + +``` +paper>=1.20.1-0 <=1.20.5 ✅ +``` + +This way it's immediately clear what the last allowed version is, and you avoid the trap described in rule 1. + +> **Note:** The system does not enforce this rule — ranges written with `>` and `<` will be accepted too. It's simply a good practice that will save you from surprises. + 9. **Advanced options (optional)** – In this section, we will create custom dependencies for your project. After clicking **“Show advanced options”**, a “Add dependency” button will appear. Clicking it allows you to **add your own dependency**. The form consists of 3 fields. diff --git a/docs/pl-PL/panel/gallery-addons.md b/docs/pl-PL/panel/gallery-addons.md index 83ef5ea..d90e59b 100644 --- a/docs/pl-PL/panel/gallery-addons.md +++ b/docs/pl-PL/panel/gallery-addons.md @@ -20,6 +20,7 @@ Oto propozycja przejrzystego i estetycznego **spisu treści** w stylu dokumentac - 2.2 [🔢 Wersjonowanie i semver](#semver) - 2.3 [📎 Wybór zależności](#depends_on) - 2.4 [⚙️ Operatory wersji: `^`, `~`, `=`](#selectors) + - 2.5 [✅ Jak tworzyć zakresy wersji, żeby uniknąć niespodzianek?](#ranges_best_practices) 3. [🧪 Opcje zaawansowane](#advanced) - 3.1 [🧩 Niestandardowe zależności i tagi](#advanced) @@ -167,6 +168,8 @@ Zaznacz wymagane zależności, jeśli Twoja paczka ich potrzebuje. Domyślnie po - `Nie wymagaj` – Twoja paczka nie ma żadnych zależności i może działać samodzielnie +> **Zalecenie:** Wybierając zależności, korzystaj z nazw takich jak `paper-api`, a nie z nazw samych paczek jak `paper`. Dlaczego? Wyjaśniamy to w sekcji [Jak tworzyć zakresy wersji, żeby uniknąć niespodzianek?](#ranges_best_practices) + #### Automatyczne instalowanie zależności: Niektóre paczki jak np. Paper mogą wymagać Javy, która zostanie zainstalowana na serwerze użytkownika. @@ -222,6 +225,54 @@ Znając tę teorię możemy tworzyć następujące wymagania względem wersji pa Aby dowiedzieć się więcej na ten temat skorzystaj z [dokumentacji 📋](https://github.com/Masterminds/semver?tab=readme-ov-file#caret-range-comparisons-major) +--- + +### ✅ Jak tworzyć zakresy wersji, żeby uniknąć niespodzianek? + + + +Dwie proste zasady, dzięki którym na serwerze użytkownika zainstaluje się dokładnie taka wersja, jakiej oczekujesz. + +#### 1. Wybieraj nazwy z końcówką `-api` (np. `paper-api`), a nie nazwy paczek (np. `paper`) + +Tworząc zależność, wybieraj nazwy takie jak `paper-api`, `purpur-api` czy `minecraft-java-server` zamiast nazw samych paczek (`paper`, `purpur`). Są to tzw. nazwy z pola `provides` — paczka silnika "udostępnia" je razem ze swoją wersją gry. + +**Dlaczego to ważne?** Wersje paczek takich jak `paper` mają na końcu dodatkowy numer po myślniku, np. `1.20.6-151` (to numer konkretnego wydania Papera). System porównujący wersje traktuje wszystko, co stoi po myślniku, jako "wersję wstępną" — czyli uznaje, że `1.20.6-151` jest **wcześniejsza (mniejsza)** niż `1.20.6`. Brzmi dziwnie, ale tak właśnie działa standard wersjonowania. Przez to zakres może objąć wersje, których wcale nie chciałeś. + +**Przykład:** + +Załóżmy, że Twoja paczka działa na wersjach od `1.20.1` do `1.20.5`, więc tworzysz zakres "mniejsze niż 1.20.6": + +``` +paper>=1.20.1-0 <1.20.6 +``` + +Niestety, wersja `1.20.6-151` mieści się w tym zakresie — system uznaje ją za mniejszą niż `1.20.6`. W efekcie użytkownikowi może zainstalować się np. `paper=1.20.6-22`, czyli dokładnie ta wersja, którą chciałeś wykluczyć! + +Nazwy takie jak `paper-api` nie mają numeru po myślniku (paczka udostępnia po prostu `paper-api=1.20.6`), więc zakres działa dokładnie tak, jak się spodziewasz: + +``` +paper-api>=1.20.1 <1.20.6 +``` + +#### 2. Podawaj granice zakresu "włącznie" (`>=` i `<=`), a nie "mniejsze/większe niż" (`<` i `>`) + +Zamiast pisać "mniejsze niż 1.20.6" (`<1.20.6`), napisz wprost "co najwyżej 1.20.5" (`<=1.20.5`). Czyli zamiast: + +``` +paper>=1.20.1-0 <1.20.6 ❌ +``` + +napisz: + +``` +paper>=1.20.1-0 <=1.20.5 ✅ +``` + +Dzięki temu od razu widać, jaka jest ostatnia dozwolona wersja, i unikasz pułapki opisanej w punkcie 1. + +> **Uwaga:** System nie pilnuje tej zasady — zakresy zapisane z `>` i `<` też zostaną przyjęte. To po prostu dobra praktyka, która oszczędzi Ci niespodzianek. + 9. **Opcje zaawansowane (opcjonalne)** - W tym punkcie będziemy tworzyć niestandardowe zależności do Twojego projektu. Po kliknięciu w **"Pokaż opcje zaawansowane"** pojawi się przycisk "Dodaj zależność". Po kliknięciu masz możliwość **dodania własnej zależności**. Formularz składa się z 3 pól. - Każde pole jest ze sobą związane. Zależność będzie konstruowana na podstawie `NAZWA+TAG`