Initial Implementation

.github/workflows/_publish.yml

@@ -24,6 +24,10 @@ on:
         description: "The type of build (e.g., nightly, release)"
         required: true
         type: string
+    secrets:
+      pypi_token:
+        description: "PyPI API Token for publishing"
+        required: false
 permissions:
   contents: read
   id-token: write  # For PyPI OIDC trusted publishing
@@ -35,8 +39,15 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - name: Download build artifact
+        if: ${{ inputs.build_location != '' }}
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16  # v4
+        with:
+          name: build-artifact-${{ inputs.build_type }}-${{ github.run_id }}
+          path: ${{ inputs.build_location }}
       - name: Publish to PyPI
         if: ${{ inputs.build_location != '' }}
         uses: pypa/gh-action-pypi-publish@81e9d935c883d0b210363ab89cf05f3894778450  # v1.8.14
         with:
           packages-dir: ${{ inputs.build_location }}
+          password: ${{ secrets.pypi_token }}

.github/workflows/_tests.yml

@@ -92,13 +92,13 @@ jobs:
           fi
           if [[ -z "$TYPES" ]] || [[ "$TYPES" == *"smoke"* && "$TYPES" == *"sanity"* && "$TYPES" == *"regression"* ]]; then
             if [ "$GENERATE_COVERAGE" == "true" ]; then
-              hatch run test:cov-${{ matrix.test-config.level }} --cov-report=xml:coverage/coverage.xml --cov-report=html:coverage/htmlcov --junitxml=reports/test-report.xml
+              hatch run test:${{ matrix.test-config.level }}-cov --cov-report=xml:coverage/coverage.xml --cov-report=html:coverage/htmlcov --junitxml=reports/test-report.xml
             else
               hatch run test:${{ matrix.test-config.level }} --junitxml=reports/test-report.xml
             fi
           else
             if [ "$GENERATE_COVERAGE" == "true" ]; then
-              hatch run test:cov-${{ matrix.test-config.level }} -m "$MARKERS" --cov-report=xml:coverage/coverage.xml --cov-report=html:coverage/htmlcov --junitxml=reports/test-report.xml
+              hatch run test:${{ matrix.test-config.level }}-cov -m "$MARKERS" --cov-report=xml:coverage/coverage.xml --cov-report=html:coverage/htmlcov --junitxml=reports/test-report.xml
             else
               hatch run test:${{ matrix.test-config.level }} -m "$MARKERS" --junitxml=reports/test-report.xml
             fi

.github/workflows/nightly.yml

@@ -72,3 +72,5 @@ jobs:
     with:
       build_type: "nightly"
       build_location: "dist/"
+    secrets:
+      pypi_token: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/release.yml

@@ -74,3 +74,5 @@ jobs:
     with:
       build_type: "release"
       build_location: "dist/"
+    secrets:
+      pypi_token: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -51,10 +51,10 @@ cmake-build-*/
 
 # VS Code / Cursor
 .vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
+.vscode/settings.json
+.vscode/tasks.json
+.vscode/launch.json
+.vscode/extensions.json
 *.code-workspace
 .history/
 .cursor/

AGENTS.md

@@ -16,7 +16,6 @@
 > 1. **Never commit secrets.** Do not add API keys, tokens, or credentials anywhere.
 > 1. **Do not modify `LICENSE` or `NOTICE`.** These are legally binding.
 > 1. **Do not modify workflow trigger conditions** without human review.
-> 1. **All new source files must include the Apache 2.0 copyright header.**
 
 ## Repository Layout
 
@@ -29,7 +28,7 @@
 
 - **Linting:** `hatch run lint:check` (Ruff & mdformat) and `hatch run types:check` (Mypy)
 - **Pre-commit:** `pre-commit run --all-files` (Runs formatting and quality checks)
-- **Testing:** `hatch run test:all` (Pytest) and `hatch run test:cov-all` (Coverage)
+- **Testing:** `hatch run test:all` (Pytest) and `hatch run test:all-cov` (Coverage)
 - **Docs:** `hatch run docs:serve` / `hatch run docs:build`
 - **Build:** `hatch build`
 

CONTRIBUTING.md

@@ -55,7 +55,6 @@ Before you start coding, please refer to our [Development Guide](DEVELOPING.md)
 
 - Write clear, concise commit messages.
 - We recommend using [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat: add submodule support`, `fix: correct PEP 440 pre-release sorting`).
-- If you are adding a new file, please include the appropriate Apache 2.0 copyright and license header at the top.
 
 ### 5. Submitting a Pull Request
 

DEVELOPING.md

@@ -37,23 +37,47 @@ docker-compose logs -f
 
 ## Local Setup
 
-If you prefer to develop directly on your host machine, this project uses [Hatch](https://hatch.pypa.io/) for environment management, dependency resolution, and building.
+If you prefer to develop directly on your host machine, this project uses [uv](https://docs.astral.sh/uv/) for environment management and dependency resolution, alongside [Hatch](https://hatch.pypa.io/) as our command orchestrator.
 
 > [!NOTE]
 > **A note on shared tooling:** This project uses [MkDocs](https://www.mkdocs.org/) for documentation.
 
 ```bash
-# 1. Install hatch globally (if not already installed)
-pipx install hatch # or pip install hatch
+# 1. Install uv and hatch globally (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install hatch
 
-# 2. Enter the default development environment
-hatch shell
+# 2. Optionally, set up a Python virtual environment
+uv venv
+source .venv/bin/activate
 
-# Or run commands directly in the environment without entering it:
+# 3. Sync the development environment (installs all dependency groups and extras)
+uv sync --all-groups --all-extras
+
+# 4. Run hatch commands directly
 hatch run test:all
 hatch run lint:check
 ```
 
+### Managing Dependencies
+
+Use `uv` to add or update dependencies efficiently:
+
+```bash
+# Add a general dependency
+uv add <package>
+
+# Add a development dependency
+uv add --group dev <package>
+
+# Add to a specific extra
+uv add <package> --optional <extra_name>
+
+# Sync targeted groups or extras
+uv sync --group dev
+uv sync --extra <extra_name>
+```
+
 ## Running Tests
 
 We maintain strict testing standards. Our tests are located in the `tests/` directory and are categorized by tier.
@@ -72,7 +96,7 @@ hatch run test:unit
 hatch run test:integration
 
 # Run all tests with coverage
-hatch run test:cov-all
+hatch run test:all-cov
 ```
 
 ## Code Quality and Formatting
@@ -101,7 +125,7 @@ We use [pre-commit](https://pre-commit.com/) to ensure code quality standards ar
 1. Install pre-commit globally or in your local virtual environment:
 
    ```bash
-   pip install pre-commit
+   uv pip install pre-commit
    ```
 
 1. Install the git hook scripts:

README.md

@@ -26,22 +26,13 @@
   <a href="https://github.com/markurtz/git-versioned/actions/workflows/main.yml">
     <img src="https://github.com/markurtz/git-versioned/actions/workflows/main.yml/badge.svg" alt="CI Status">
   </a>
-  <!-- Uncomment to display code coverage:
-  <a href="https://codecov.io/gh/markurtz/git-versioned">
-    <img src="https://codecov.io/gh/markurtz/git-versioned/branch/main/graph/badge.svg" alt="Coverage">
-  </a>
-  -->
   <br/>
   <!-- Issues & Support -->
-  <a href="https://github.com/markurtz/git-versioned/issues?q=is%3Aissue+is%3Aclosed">
-    <img src="https://img.shields.io/github/issues-closed/markurtz/git-versioned?label=Issues%20Closed" alt="Closed Issues">
-  </a>
-  <!-- Uncomment to display open issues:
   <a href="https://github.com/markurtz/git-versioned/issues?q=is%3Aissue+is%3Aopen">
     <img src="https://img.shields.io/github/issues/markurtz/git-versioned?label=Issues%20Open" alt="Open Issues">
   </a>
-  -->
-  <a href="https://opensource.org/licenses/Apache-2.0">
+
+<a href="https://opensource.org/licenses/Apache-2.0">
     <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
   </a>
 </p>
@@ -83,11 +74,20 @@ GitVersioned is currently under active development. Keep an eye on this section
 
 ## Quick Start
 
-```bash
-pip install gitversioned
+### Installation & Configuration
+
+GitVersioned is primarily used as a build plugin. The preferred pathway is to configure it in your `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["hatchling", "gitversioned"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "gitversioned"
 ```
 
-For full installation options (from source, Docker, platform-specific notes) and step-by-step onboarding, see the **[Getting Started guide](https://markurtz.github.io/git-versioned/getting-started/)**.
+For full installation options, Setuptools alternatives, and step-by-step onboarding, see the **[Getting Started guide](https://markurtz.github.io/git-versioned/getting-started/)**.
 
 ## Core Concepts