Rozdział 23 · Część VI · Wydanie pierwszej wersji

Dokumentacja, wersja i pierwsze wydanie

MAJOR.MINOR.PATCH, CHANGELOG.md, Git tag i GitHub Release dają projektowi punkt, do którego można wrócić i do którego można się odwołać.

SafeSort · Część 6 z 6

Git i GitHub→Planowanie→Projekt→Wdrożenie→Testy i CI→Premiera

Projekt gotowy, sprawdzony testami i podłączony do automatycznej weryfikacji. Skończyliśmy pierwszą użyteczną wersję SafeSort.. Teraz potrzebuje numeru, aby odróżnić ją od przyszłych zmian. Ten numer już zapisaliśmy w pyproject.toml też w części III, gdzie było to tylko techniczne Pole. Teraz zobaczmy, co to oznacza.

W 0.1.0 każda z trzech liczb odpowiada za inny rodzaj zmiany

Wersowanie semantyczne

Ten schemat nazywa się semantyczne wersjonowanie (Semantic Versioning, SemVer), czyli umowa dotycząca zapisu numeru wersji jako MAJOR.MINOR.PATCH:

Część pokoju	Zmiany podczas
MAJOR	niekompatybilne zmiany; stary sposób używania przestaje działać
MINOR	dodano nową funkcję, zachowano stare zachowanie
PATCH	błąd został naprawiony, zachowanie zasadniczo się nie zmieniło

Umowa, a nie prawo fizyki

wersjonowanie semantyczne ustanawia powszechnie przyjętą konwencję, ale nie jest wbudowana w narzędzia: nic technicznie nie stoi na przeszkodzie, by złamać jej znaczenie. Zaletą z tego jest tylko tyle, na ile sam projekt konsekwentnie go przestrzega. To jest wskazówka dla tych, którzy instalują pakiet i chcą zrozumieć, czego mogą się spodziewać po nowej wersji.

Pierwsza wersja SafeSort ma numer 0.1.0. Wersja mniejsza niż 1 tradycyjnie oznacza „interfejs może jeszcze ulec zmianie bez dodatkowej zgody”.

Co się zmieniło w tej wersji: CHANGELOG

CHANGELOG.md

## [0.1.0]

### Added

- scan, plan, apply, duplicates, undo commands

### Safety

- dry-run by default (scan/plan/duplicates never modify files)
- no automatic duplicate deletion
- no silent overwrite of existing files

CHANGELOG opisuje tylko rzeczywiste wersje

CHANGELOG nie powinno pojawiać się wcześniejszych wersji, które nie istniały. Opisuje to wprowadzone zmiany zaczynające się od pierwszej wersji projektu.

Zbieraj wheel i sdist

Wydanie zaczyna się od drzewa źródłowego, ale użytkownik otrzymuje distribution artifacts. Drużyna python -m build tworzy oba standardowe formaty:

Terminal (główna repozytorium SafeSort)

python -m pip install --upgrade build
python -m build

dist/

safesort-0.1.0-py3-none-any.whl

safesort-0.1.0.tar.gz

wheel zawiera gotowe archiwum Python distribution; sdist zawiera źródła do montażu

Artefakt	Cel
wheel (.whl)	gotowe archiwum distribution: instalacja zwykle nie uruchamia kompilacji projektu
sdist (.tar.gz)	archiwum źródłowe i metadane, z którego narzędzie może zbierać wheel

Smoke test w czystym środowisku

Editable install weryfikuje projekt, ale nie dowodzi, że zbudowany wheel zawiera niezbędne pliki i console script. Dlatego zainstaluj artifact w nowym środowisku:

POSIX shell

python -m venv .release-smoke
source .release-smoke/bin/activate
python -m pip install dist/safesort-0.1.0-py3-none-any.whl
python -c "import safesort; print(safesort.__file__)"
safesort --help
deactivate

W Windows aktywacja odbywa się poleceniem .release-smoke\Scripts\activate. Tak samo zainstalowano distribution, a nie źródła src/.

GitHub Release jest zbudowany na

Git tag i GitHub Release: różne obiekty

Tag (tag) przechowuje odniesienie Git-a do konkretnego commitu i zazwyczaj odpowiada numerowi wersji. Technicznie rzecz biorąc, tag można przenieść lub usunąć, ale Opublikowane tagi release- są uznawane za niezmienne w projekcie polityki. GitHub Release służy jako osobny obiekt GitHub utworzony wokół tagu. Ma Strona z opisem i dołączonymi tagami artifacts. Push sama nie tworzy Release.

Tag wersji dotyczy całego repozytorium w całości, nie tylko w jednej jego części. Dlatego SafeSort żyje w swoim własnym repozytorium Cartesian-School/safesort, nie tylko w podkatalogu kursów: git tag v0.1.0 tutaj jednoznacznie oznacza „wersja 0.1.0 SafeSort”, bez dwuznaczności.

~/safesort $ git tag -a v0.1.0 -m "SafeSort 0.1.0 — first release"
~/safesort $ git push origin v0.1.0
To https://github.com/Cartesian-School/safesort.git
 * [new tag]         v0.1.0 -> v0.1.0

Następnie w interfejsie webowym GitHub otwórz Releases → Draft a new release, wybierz istniejący v0.1.0, dodaj fragment CHANGELOG i załącz oba pliki z dist/. Następnie tag ma czytelną stronę wydania oraz dostępne do pobrania artifacts.

Strona wydania SafeSort 0.1.0 dla GitHub: tytułu, Latest etykiety, opisu, pip install poleceń, załączników, wheel i sdist — Wydanie SafeSort 0.1.0: Tagi, notatki do patcha oraz pakiety wheel i sdist.

Wydanie jest tworzone dopiero po tym, jak wszystko inne jest gotowe

Tag i release pojawiły się w ostatnim kroku, gdy CI był już zielony, CHANGELOG.md opisywały prawdziwe zmiany, editable install wheel/sdist budowy i komendę safesort --help zostały ponownie sprawdzone w czystym środowisku. Bez tych sprawdzeń numer wersji niczego nie gwarantuje.

Publikacja do PyPI pozostaje poza wersją 0.1.0

Instalacja przez pip install git+https://github.com/Cartesian-School/safesort.git@v0.1.0 wystarczające do tworzenia i użytku osobistego. Publikuj pakiet na PyPI, aby mógł zostać zainstalowany przez zespół pip install safesort bez odwołania do repozytorium, pozostaje osobnym tematem z własnymi wymaganiami dotyczącymi konta i publikacji. Wersja 0.1.0 świadomie tego nie dotyczy.

Krótko

MAJOR.MINOR.PATCH określa konwencję numeru wersji, a nie regułę wbudowaną w narzędzia.
python-m build tworzy wheel i sdist; czyste środowisko sprawdza instalację wheel i console script.
Git tag i GitHub Release reprezentują różne obiekty; Release jest tworzony wokół tagu i przechowuje artifacts.

Oficjalna dokumentacja

Packaging flow

Packaging Python Projects — Generating distribution archives

Semantic Versioning 2.0.0

Managing releases in a repository

← Back

GitHub Actions

Następny →

Podsumowanie rozdziału