Adding version with setuptools_scm + uv + hatch + github actions

[smorin]

Let me describe this project in a more natural way that captures the complete workflow and dependencies.

Python Project Automation Setup

What We're Trying to Achieve

We want to create a seamless development environment where version management happens automatically through Git operations, using SetupTools SCM to handle versioning. This needs to work smoothly with the uv package manager for daily development and hatch as our build system. The end result should be a project where developers can focus on coding while the versioning and build processes happen reliably in the background.

Core Components and Dependencies

• SetupTools SCM for version management
• uv for package management and daily development
• hatch as the build system
• GitHub Actions for automation
• Git for version control and tagging

Configuration Files Needed

1. pyproject.toml needs to be set up with:

   • SetupTools SCM configuration for version management
   • hatch build system settings
   • Project dependencies and development dependencies
   • Version management settings

2. GitHub Actions workflow files for:

   • Automated version bumping
   • Release management
   • Build validation
   • Tag handling

Development Workflow Documentation

The README should walk through the complete workflow:

1. Initial Setup

   • How to install the required tools (uv, hatch)
   • Project clone and initial configuration
   • Setting up your development environment

2. Daily Development

   • Using uv for dependency management
   • Local build and test procedures
   • How versioning works during development

3. Version Management

   • How to create and push tags
   • Example of version bumping
   • Verifying current version
   • Understanding the version format

4. Validation Steps

   • Building the project with specific commands
   • Checking the current version
   • Verifying version increments
   • Testing the build artifacts

Practical Examples Needed

The documentation should include real-world examples:

# Example of creating a new version
git tag -a v0.1.0 -m "Initial release"
git push origin v0.1.0

# Example of checking the current version
uv build .
python -c "import my_package; print(my_package.__version__)"

# Example of local development build
uv pip install -e .

Deliverables

1. Working Configuration

   • Complete pyproject.toml
   • GitHub Actions workflow files
   • Any necessary source code modifications

2. Comprehensive README

   • Step-by-step setup instructions
   • Clear examples with command outputs
   • Troubleshooting section
   • Best practices for version management

3. Validation Process

   • Test scripts for version checking
   • Build verification steps
   • GitHub Actions validation

The goal is to make this as maintainable as possible, with clear documentation that helps both new and experienced developers understand how to work with the project's versioning and build system.

Answer the question how to get it to work with uv e.g "uv pip install --editable ".[dev]"

------------------------- Notes on github actions ---------------------------------------------------------------

• uses: actions/checkout@v4
  with:
  fetch-depth: 0 # Required for git history

---

fetch-depth: 0 in GitHub Actions tells the checkout action to fetch the complete Git history instead of just the latest commit.

Key impacts:

• Gets all commits and tags
• Required for setuptools_scm to work
• Larger checkout size/time
• Enables version calculations

Default (fetch-depth: 1):

• Only latest commit
• Faster
• Smaller
• No version history

---------------- first draft of documentation ------------------------------------
NOTE: More details should be added

Versioning and Releases

This project uses setuptools_scm to automatically manage the project version based on Git tags and commit history. This means the version is dynamically generated during installation and build processes.

Understanding Versions

• Development Versions: During development, the version will typically look something like 0.1.0.dev1+gabcdef12 or 0.1.0+gabcdef12.dirty. This indicates a version based on a commit after the last tag, and potentially with uncommitted changes (.dirty).
• Release Versions: When you create a Git tag (e.g., v1.0.0), setuptools_scm will recognize this tag and produce a clean version like 1.0.0 for releases built from that tag.

Key Command-Line Interactions (Indirectly related to setuptools_scm)

1. Installing the Package (and Generating the Version):

   To install the package (and trigger version generation by setuptools_scm), use pip:

   pip install .
   

Testing Package Version (with uv)

After installing your package using uv, you'll likely want to verify the version that setuptools_scm has generated. uv provides a convenient way to run Python code within its managed environment to check this.

Recommended Method: Using uv run python -c

The most straightforward and recommended way to check the package version after installing with uv is to use the uv run python -c command. This command executes a Python snippet directly within the environment where uv has installed your package, ensuring you're testing the correct version.

To check the version, use the following command in your terminal, replacing your_package_name with the actual name of your Python package:

uv run python -c "import your_package_name; print(your_package_name.__version__)"