Add Good Practices for versioning

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?
+
+<a id="ranges_best_practices"></a>
+
+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.
+
 <a id="advanced"></a>
 
 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.

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?
+
+<a id="ranges_best_practices"></a>
+
+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.
+
 <a  id="advanced"></a> 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`