GitHub releases a Semantic Versioning

Ucząc się, jak działają wydania (releases) na GitHubie, znalazłem na nim taką stronę, na której jest napisane:

(...)

4. Type a version number for your release. Versions are based on Git tags. We recommend naming tags that fit within semantic versioning.

(...)

"Pięknie", pomyślałem, "więc jeden problem został rozwiązany, bo wystarczy trzymać się podanej specyfikacji i mogę zacząć nazywać swoje oprogramowanie 1.0.0, 1.0.1...". Jednak, jak się okazało, nie jest tak prosto. Wspomniane "semantic versioning" opisane jest na tej stronie https://semver.org/ i jest tam napisane:

For this system to work, you first need to declare a public API.

a dalej nawet

Software using Semantic Versioning MUST declare a public API.

Więc nie rozumiem: czy GitHub tylko tak ogólnie o tym wspomniał, czy ja czegoś w dokumentacji Semantic Versioning nie dotyczałem? Chodzi mi o to, że API nie jest przecież wymagane do wersjonowania.

Semver dotyczy softu deklarującego publiczne API, czyli głównie bibliotek. Dla użytkowników bibliotek ważna jest wiedza na temat kompatybilności pomiędzy kolejnymi wersjami, a semver pozwala na łatwe zorientowanie się w tej sprawie. Jednak jest to tylko konwencja, której nie musisz stosować.
Zwróć jednak uwagę, że pod publiczne API można podciągnąć takie rzeczy, jak format parametrów przyjmowanych z terminala czy format używanych plików, więc i program użytkowy można pod to podciągnąć ;)

Więc nie rozumiem: czy GitHub tylko tak ogólnie o tym wspomniał, czy ja czegoś w dokumentacji Semantic Versioning nie dotyczałem? Chodzi mi o to, że API nie jest przecież wymagane do wersjonowania.

API nie jest wymagane do wersjonowania, ale SemVer jest oparte właśnie o publiczne API.

Semantic Versioning 2.0.0
Summary
Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Wersja MAJOR zwiększa się podczas niekompatybilnych wstecznie zmian w publicznym API.
Wersja MINOR zwiększa się podczas kompatybilnych wstecznie zmian w publicznym API.
Wersja PATCH zwiększa się bez zmian w publicznym API.

Jeśli wytniesz odniesienia do publicznego API z definicji SemVer to zostaniesz z niczym, a więc SemVer straci zupełnie sens.

Silv napisał(a):

Więc nie rozumiem: czy GitHub tylko tak ogólnie o tym wspomniał, czy ja czegoś w dokumentacji Semantic Versioning nie dotyczałem? Chodzi mi o to, że API nie jest przecież wymagane do wersjonowania.

Bardzo dobrze odpowiedział @mad_penguin, ale jak naprawdę nie masz co podciągnąc pod 'public API', to będziesz po prostu wciąż w wersji 1.y.z i już... :)

mad_penguin napisał(a):

Semver dotyczy softu deklarującego publiczne API, czyli głównie bibliotek. Dla użytkowników bibliotek ważna jest wiedza na temat kompatybilności pomiędzy kolejnymi wersjami, a semver pozwala na łatwe zorientowanie się w tej sprawie. Jednak jest to tylko konwencja, której nie musisz stosować.

Wibowit napisał(a):

API nie jest wymagane do wersjonowania, ale SemVer jest oparte właśnie o publiczne API.

Konwencja, właśnie. Tak się domyślam. Zastanawiam się teraz, że może GitHub świadomie wspomniał jedynie o tej konwencji, bo na przykład większość rzeczy na nim to biblioteki? Mógł o dowolnej innej, ale wybrał tę. Trochę to nieprecyzyjne, tak sobie myślę.

Zwróć jednak uwagę, że pod publiczne API można podciągnąć takie rzeczy, jak format parametrów przyjmowanych z terminala czy format używanych plików, więc i program użytkowy można pod to podciągnąć ;)

Tak bym właśnie chciał zrobić, ale w sumie to jeszcze muszę zobaczyć/poczytać, bo słowo "podciągać" przy moim doświadczeniu odczuwam jako zbyt niebezpieczne. ;)