Python Pypi Package Builder

Canonical form:  N[.N]+[{a|b|rc}N][.postN][.devN]

1.0.0            Stable release
1.0.0a1          Alpha pre-release
1.0.0b2          Beta pre-release
1.0.0rc1         Release candidate
1.0.0.post1      Post-release (packaging fix; same codebase)
1.0.0.dev1       Development snapshot — DO NOT upload to PyPI
2.0.0            Major release (breaking changes)

1!1.0.0          Epoch 1; used when you need to skip ahead of an old scheme

MAJOR  Increment when you make incompatible API changes (rename, remove, break)
MINOR  Increment when you add functionality backward-compatibly (new features)
PATCH  Increment when you make backward-compatible bug fixes

Examples:
  1.0.0 → 1.0.1   Bug fix, no API change
  1.0.0 → 1.1.0   New method added; existing API intact
  1.0.0 → 2.0.0   Public method renamed or removed

1.0.0a1    Alpha-1: very early; expect bugs; API may change
1.0.0b1    Beta-1:  feature-complete; API stabilising; seek broader feedback
1.0.0rc1   Release candidate: code-frozen; final testing before stable
1.0.0      Stable: ready for production

Start:       1.0.0a1
More alphas: 1.0.0a2, 1.0.0a3
Move to beta: 1.0.0b1  (reset counter)
Move to RC:  1.0.0rc1
Stable:      1.0.0

Is the project using git and tagging releases with version tags?
├── YES → setuptools + setuptools_scm  (DEFAULT — best for most projects)
│         Git tag v1.0.0 becomes the installed version automatically.
│         Zero manual version bumping.
│
└── NO — Is the project a simple, single-module library with infrequent releases?
          ├── YES → flit
          │         Set __version__ = "1.0.0" in __init__.py.
          │         Update manually before each release.
          │
          └── NO — Does the team want an integrated build + dep management tool?
                    ├── YES → poetry
                    │         Manage version in [tool.poetry] version field.
                    │
                    └── NO → hatchling (modern, fast, pure-Python)
                              Use hatch-vcs plugin for dynamic versioning
                              or set version manually in [project].

Does the package have C/Cython/Fortran extensions?
└── YES (always) → setuptools (only backend with native extension support)

[build-system]
requires      = ["setuptools>=70", "setuptools_scm>=8"]
build-backend = "setuptools.backends.legacy:build"

[project]
name    = "your-package"
dynamic = ["version"]

[tool.setuptools_scm]
version_scheme = "post-release"
local_scheme   = "no-local-version"   # Prevents +g<hash> from breaking PyPI

# your_package/__init__.py
from importlib.metadata import version, PackageNotFoundError

try:
    __version__ = version("your-package")
except PackageNotFoundError:
    # Package is not installed (running from a source checkout without pip install -e .)
    __version__ = "0.0.0.dev0"

__all__ = ["__version__"]

git tag v1.0.0            →  installed_version = "1.0.0"
3 commits after v1.0.0    →  installed_version = "1.0.0.post3+g<hash>"  (dev only)
git tag v1.1.0            →  installed_version = "1.1.0"

- uses: actions/checkout@v4
  with:
    fetch-depth: 0    # REQUIRED — without this, git has no tag history
                      # setuptools_scm falls back to 0.0.0+d<date> silently

# Check what version setuptools_scm would produce right now:
python -m setuptools_scm

# If you see 0.0.0+d... it means:
# 1. No tags reachable from HEAD, OR
# 2. fetch-depth: 0 was not set in CI

[build-system]
requires      = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[project]
name    = "your-package"
dynamic = ["version"]

[tool.hatch.version]
source = "vcs"

[tool.hatch.build.hooks.vcs]
version-file = "src/your_package/_version.py"

from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("your-package")
except PackageNotFoundError:
    __version__ = "0.0.0.dev0"

[build-system]
requires      = ["flit_core>=3.9"]
build-backend = "flit_core.buildapi"

[project]
name    = "your-package"
dynamic = ["version", "description"]

"""your-package — a focused, single-purpose utility."""
__version__ = "1.2.0"   # flit reads this; update manually before each release

# 1. Bump __version__ in __init__.py
# 2. Update CHANGELOG.md
# 3. Commit
git add src/your_package/__init__.py CHANGELOG.md
git commit -m "chore: release v1.2.0"
# 4. Tag (flit can also publish directly)
git tag v1.2.0
git push origin v1.2.0
# 5. Build and publish
flit publish
# OR
python -m build && twine upload dist/*

[build-system]
requires      = ["hatchling"]
build-backend = "hatchling.build"

[project]
name    = "your-package"
version = "1.0.0"   # Manual; update before each release

# BAD — when using setuptools_scm, hatchling, or poetry:
__version__ = "1.0.0"    # gets stale; diverges from the installed package version

# GOOD — works for all backends except flit:
from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("your-package")
except PackageNotFoundError:
    __version__ = "0.0.0.dev0"

# [project] dependencies — library best practices:

"httpx>=0.24"            # Minimum only — PREFERRED; lets users upgrade freely
"httpx>=0.24,<2.0"       # Upper bound only when a known breaking change exists in next major
"requests>=2.28,<3.0"    # Acceptable for well-known major-version breaks

# Application / CLI (pinning is fine):
"httpx==0.27.2"          # Lock exact version for reproducible deploys

# NEVER in a library:
# "httpx~=0.24.0"        # Too tight; blocks minor upgrades
# "httpx==0.27.*"        # Not valid PEP 440
# "httpx"                # No constraint; fragile against future breakage

# Step 1: Tag the release (triggers CI publish.yml automatically if configured)
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

# Step 2 (manual fallback only): Build locally
python -m build
# Produces:
#   dist/your_package-1.2.3.tar.gz   (sdist)
#   dist/your_package-1.2.3-py3-none-any.whl  (wheel)

# Step 3: Validate
twine check dist/*

# Step 4: Test on TestPyPI first (first release or major change)
twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package==1.2.3

# Step 5: Publish to production PyPI
twine upload dist/*
# OR via GitHub Actions (recommended):
# push the tag → publish.yml runs → pypa/gh-action-pypi-publish handles upload via OIDC

# Step 6: Verify
pip install your-package==1.2.3
python -c "import your_package; print(your_package.__version__)"