Initial Implementation

[markurtz]

Description

This PR introduces the core implementation for the initial v0.1.0 release of git-versioned. It transitions the project from a boilerplate state into a fully functional, PEP 440-compliant Python versioning tool powered by Git metadata.

Key Additions:

• Build Backend Plugins: Implemented PEP 517-compliant versioning plugins for both hatchling and setuptools.
• Core Versioning Engine: Added versioning.py, git.py, and environment.py to intelligently parse Git history (tags, commits, branches) and dynamically generate project versions.
• Configuration Management: Introduced robust, pydantic-driven settings (settings.py) allowing fine-grained customization via pyproject.toml, setup.cfg, or setup.py.
• Documentation: Completely overhauled the MkDocs material site (docs/), providing comprehensive guides for concepts, configuration, hatchling, setuptools, and templates.
• Examples: Created 15 functional example projects in the examples/ directory demonstrating diverse use cases and configurations across both backends.
• Testing: Added an extensive suite of unit, integration, and End-to-End (E2E) tests ensuring robust validation of Git resolution and build-time injection.
• CI/CD & Tooling: Migrated underlying dependency management to uv (uv.lock), updated GitHub Actions workflows to automate tests, coverage reporting, documentation deployment, and PyPI publishing.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update (changes to README.md, SUPPORT.md, docstrings, etc.)
• 🛠️ Maintenance/Refactoring (non-breaking change that improves code structure or quality)

Test Plan

Automated tests have been comprehensively added:

• Unit Tests: Coverage for Git utilities, environment parsers, settings validation, and versioning logic.
• Integration Tests: Verification of plugin entry points and configuration parsing behavior.
• E2E Tests: Validation of actual hatch build and python -m build executions to ensure wheels and source distributions contain the correctly resolved version.py.

To manually verify:

1. Run hatch run test:all to execute the full test suite.
2. Run hatch run test:all-cov to verify coverage.
3. CD into any of the 15 projects in examples/ and run hatch build (or python -m build) to verify the generated artifacts behave as documented.

Related Issues

• Initial Implementation (v0.1.0)

Screenshots / Visuals (if applicable)

N/A - Build backend tool. Documentation updates can be viewed locally via hatch run docs:serve.

Use of AI

• Includes AI-assisted code completion
• Includes code generated by an AI application
• Includes AI-generated tests (NOTE: AI written tests should have a docstring that includes ## WRITTEN BY AI ##)

Checklist

Important

Please review and complete this checklist before submitting your PR. This helps our maintainers process your contribution faster and ensures it meets the quality standards of gitversioned.

• "I certify that all code in this PR is my own, except as noted below."
• I have read the CONTRIBUTING.md guide.
• My code follows the established style guidelines of gitversioned.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings or errors.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.

[github-actions]

CI Development Pipeline Status

❌ Pipeline: Failed or was cancelled. Check logs

[Copilot]

Pull request overview

Implements the initial functional gitversioned release by adding the core version-resolution engine, build-backend integrations (Hatchling + Setuptools), and the surrounding configuration/logging/test/docs scaffolding to move the project beyond boilerplate.

Changes:

• Added Pydantic-based configuration model + helper types/coercers, plus build-environment introspection utilities.
• Implemented Hatchling and Setuptools plugin entrypoints to resolve versions from Git metadata and (optionally) generate version.py.
• Added/expanded unit + integration + E2E tests, updated docs/MkDocs config, examples, and CI workflows/tooling to support the new functionality.

Reviewed changes

Copilot reviewed 124 out of 129 changed files in this pull request and generated 38 comments.

Show a summary per file

File	Description
.github/workflows/_publish.yml	Adds artifact download and optional PyPI token wiring for publishing.
.github/workflows/_tests.yml	Updates Hatch script names for coverage runs.
.github/workflows/nightly.yml	Passes PyPI token into reusable publish workflow.
.github/workflows/release.yml	Passes PyPI token into reusable publish workflow.
.env.example	Removes boilerplate environment template.
.gitignore	Adjusts VS Code ignore rules.
AGENTS.md	Updates documented coverage command name.
DEVELOPING.md	Updates local dev workflow to use uv + Hatch command orchestration.
README.md	Updates quick start guidance and installation instructions.
docs/examples/index.md	Replaces placeholder examples page with links to concrete examples.
docs/getting-started/installation.md	Expands installation docs (pip/uv, build setup).
docs/getting-started/quickstart.md	Reworks quickstart toward build-plugin workflow.
docs/getting-started/workflows.md	Updates workflows section (CI/CD example).
docs/guides/configuration.md	Adds configuration reference/guide content.
docs/guides/concepts.md	Adds conceptual documentation for resolution algorithm.
docs/guides/hatchling.md	Adds Hatchling integration guide.
docs/guides/index.md	Updates guides index to link to new guides.
docs/guides/setuptools.md	Adds Setuptools integration guide.
docs/guides/templates.md	Adds templates/formatting guide for generated version files.
docs/index.md	Updates docs homepage quick install section.
docs/reference/api.md	Adds mkdocstrings API reference page.
docs/reference/index.md	Updates reference landing page and adds Python API usage snippet.
examples/README.md	Replaces placeholder table with a curated example list.
examples/hatchling-hatch-vars/README.md	Adds README for hatchling-hatch-vars example.
examples/hatchling-hatch-vars/pyproject.toml	Adds hatchling-hatch-vars example project config.
examples/hatchling-hatch-vars/src/hatchling_hatch_vars/__init__.py	Adds example package stub.
examples/hatchling-hatch-vars/src/hatchling_hatch_vars/main.py	Adds example entry module.
examples/hatchling-tool-table/README.md	Adds README for hatchling-tool-table example.
examples/hatchling-tool-table/pyproject.toml	Adds hatchling-tool-table example project config.
examples/hatchling-tool-table/src/hatchling_tool_table/__init__.py	Adds example package stub.
examples/hatchling-tool-table/src/hatchling_tool_table/main.py	Adds example entry module.
examples/hatchling-version-branch/README.md	Adds README for hatchling-version-branch example.
examples/hatchling-version-branch/pyproject.toml	Adds hatchling-version-branch example project config.
examples/hatchling-version-branch/src/hatchling_version_branch/__init__.py	Adds example package stub.
examples/hatchling-version-branch/src/hatchling_version_branch/main.py	Adds example entry module.
examples/hatchling-version-commits/README.md	Adds README for hatchling-version-commits example.
examples/hatchling-version-commits/pyproject.toml	Adds hatchling-version-commits example project config.
examples/hatchling-version-commits/src/hatchling_version_commits/__init__.py	Adds example package stub.
examples/hatchling-version-commits/src/hatchling_version_commits/main.py	Adds example entry module.
examples/hatchling-version-file/README.md	Adds README for hatchling-version-file example.
examples/hatchling-version-file/pyproject.toml	Adds hatchling-version-file example project config.
examples/hatchling-version-file/src/hatchling_version_file/__init__.py	Adds example package stub.
examples/hatchling-version-file/src/hatchling_version_file/main.py	Adds example entry module.
examples/hatchling-version-file/src/hatchling_version_file/version.py	Includes a sample generated version module in the example.
examples/hatchling-version-function/README.md	Adds README for hatchling-version-function example.
examples/hatchling-version-function/pyproject.toml	Adds hatchling-version-function example project config.
examples/hatchling-version-function/src/hatchling_version_function/__init__.py	Adds example package stub.
examples/hatchling-version-function/src/hatchling_version_function/main.py	Adds example entry module.
examples/hatchling-version-tags/README.md	Adds README for hatchling-version-tags example.
examples/hatchling-version-tags/pyproject.toml	Adds hatchling-version-tags example project config.
examples/hatchling-version-tags/src/hatchling_version_tags/__init__.py	Adds example package stub.
examples/hatchling-version-tags/src/hatchling_version_tags/main.py	Adds example entry module.
examples/setuptools-setup-cfg/README.md	Adds README for setuptools-setup-cfg example.
examples/setuptools-setup-cfg/setup.cfg	Adds setuptools-setup-cfg configuration file.
examples/setuptools-setup-cfg/setup.py	Adds setuptools-setup-cfg setup script.
examples/setuptools-setup-cfg/src/setuptools_setup_cfg/__init__.py	Adds example package stub.
examples/setuptools-setup-cfg/src/setuptools_setup_cfg/main.py	Adds example entry module.
examples/setuptools-setup-py/README.md	Adds README for setuptools-setup-py example.
examples/setuptools-setup-py/setup.py	Adds setuptools-setup-py setup script example.
examples/setuptools-setup-py/src/setuptools_setup_py/__init__.py	Adds example package stub.
examples/setuptools-setup-py/src/setuptools_setup_py/main.py	Adds example entry module.
examples/setuptools-tool-table/README.md	Adds README for setuptools-tool-table example.
examples/setuptools-tool-table/pyproject.toml	Adds setuptools-tool-table example project config.
examples/setuptools-tool-table/src/setuptools_tool_table/__init__.py	Adds example package stub.
examples/setuptools-tool-table/src/setuptools_tool_table/main.py	Adds example entry module.
examples/setuptools-version-branch/README.md	Adds README for setuptools-version-branch example.
examples/setuptools-version-branch/pyproject.toml	Adds setuptools-version-branch example project config.
examples/setuptools-version-branch/src/setuptools_version_branch/__init__.py	Adds example package stub.
examples/setuptools-version-branch/src/setuptools_version_branch/main.py	Adds example entry module.
examples/setuptools-version-commits/README.md	Adds README for setuptools-version-commits example.
examples/setuptools-version-commits/pyproject.toml	Adds setuptools-version-commits example project config.
examples/setuptools-version-commits/src/setuptools_version_commits/__init__.py	Adds example package stub.
examples/setuptools-version-commits/src/setuptools_version_commits/main.py	Adds example entry module.
examples/setuptools-version-file/README.md	Adds README for setuptools-version-file example.
examples/setuptools-version-file/pyproject.toml	Adds setuptools-version-file example project config.
examples/setuptools-version-file/src/setuptools_version_file/__init__.py	Adds example package stub.
examples/setuptools-version-file/src/setuptools_version_file/main.py	Adds example entry module.
examples/setuptools-version-function/README.md	Adds README for setuptools-version-function example.
examples/setuptools-version-function/pyproject.toml	Adds setuptools-version-function example project config.
examples/setuptools-version-function/src/setuptools_version_function/__init__.py	Adds example package stub.
examples/setuptools-version-function/src/setuptools_version_function/main.py	Adds example entry module.
examples/setuptools-version-tags/README.md	Adds README for setuptools-version-tags example.
examples/setuptools-version-tags/pyproject.toml	Adds setuptools-version-tags example project config.
examples/setuptools-version-tags/src/setuptools_version_tags/__init__.py	Adds example package stub.
examples/setuptools-version-tags/src/setuptools_version_tags/main.py	Adds example entry module.
mkdocs.yml	Enables additional MkDocs Material plugins/extensions and refines configuration.
pyproject.toml	Adds runtime/development dependencies, entry points, Hatch env scripts, and tool configs.
src/gitversioned/__init__.py	Exposes public API, version constant, and configures logging on import.
src/gitversioned/__main__.py	Removes the previous placeholder CLI entrypoint.
src/gitversioned/compat.py	Adds optional-dependency import shims.
src/gitversioned/logging.py	Adds Loguru + Pydantic logging configuration with optional OTel formatting.
src/gitversioned/plugins/__init__.py	Adds plugin package documentation.
src/gitversioned/plugins/hatchling_plugin.py	Adds Hatchling version source plugin implementation.
src/gitversioned/plugins/setuptools_plugin.py	Adds Setuptools finalize hook + setup keyword handler for version injection.
src/gitversioned/settings.py	Adds Settings model + setup.cfg settings source.
src/gitversioned/templates/dev.py.template	Adds template for dev/dirty builds’ generated version module.
src/gitversioned/templates/release.py.template	Adds template for release builds’ generated version module.
src/gitversioned/utils/__init__.py	Adds utils package exports.
src/gitversioned/utils/environment.py	Adds BuildEnvironment model and CI/RAM/user introspection helpers.
src/gitversioned/utils/pydantic.py	Adds Pydantic validators and Ensure* types for coercion.
tests/__init__.py	Makes tests importable as a package.
tests/conftest.py	Hooks Loguru into pytest caplog.
tests/e2e/conftest.py	Adds E2E GitRepoHelper fixture.
tests/e2e/test_builds.py	Adds E2E build tests for Hatch and Setuptools builds.
tests/e2e/test_e2e.py	Removes placeholder E2E tests.
tests/integration/conftest.py	Adds GitRepoHelper for integration tests.
tests/integration/test_integration.py	Removes placeholder integration tests.
tests/integration/test_plugins.py	Adds integration coverage for both plugin entrypoints.
tests/integration/test_versioning.py	Adds integration tests for version resolution across repo states.
tests/unit/.gitkeep	Removes unit-tests placeholder file.
tests/unit/plugins/__init__.py	Adds unit test package init for plugins tests.
tests/unit/plugins/test_setuptools_plugin.py	Adds unit tests for Setuptools plugin hooks.
tests/unit/test_compat.py	Adds tests for optional-dependency compat shims.
tests/unit/test_hatchling_plugin.py	Adds unit tests for Hatchling plugin behavior.
tests/unit/test_logging.py	Adds unit tests for logging settings and configuration.
tests/unit/test_settings.py	Adds unit tests for Settings sources and validation.
tests/unit/test_unit.py	Removes placeholder unit tests.
tests/unit/utils/__init__.py	Adds unit test package init for utils tests.
tests/unit/utils/test_environment.py	Adds unit tests for environment utilities and model.
tests/unit/utils/test_pydantic.py	Adds unit tests for Pydantic coercion helpers and Ensure* types.

Comments suppressed due to low confidence (2)

docs/getting-started/installation.md:80

• This page instructs users to run gitversioned --version, but this PR removes the CLI entrypoint (src/gitversioned/__main__.py) and the project.scripts console script in pyproject.toml. Unless a new CLI entrypoint is provided elsewhere, these verification steps will fail and should be removed/updated.

### Verify the Installation

After installation, confirm it is working correctly:

```bash
gitversioned --version

You should see output similar to:

gitversioned 0.1.0

**docs/getting-started/workflows.md:35**
* The workflow example runs `gitversioned generate`, but this PR removes the CLI entrypoint (`src/gitversioned/__main__.py`) and the `project.scripts` console script. Unless a new CLI is added, this command won’t exist; update the workflow to demonstrate build-backend usage (e.g., `hatch build` / `python -m build`) or restore the CLI.

  - name: Install gitversioned
    run: |
      # Or optionally using uv: uv pip install gitversioned
      pip install gitversioned

  - name: Generate version metadata
    run: gitversioned generate

</details>



---

💡 <a href="/markurtz/git-versioned/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

[github-actions]

CI Development Pipeline Status

✅ Pipeline: Completed successfully. View Run Details

[github-actions]

CI Development Pipeline Status

❌ Pipeline: Failed or was cancelled. Check logs

[github-actions]

CI Development Pipeline Status

✅ Pipeline: Completed successfully. View Run Details