feat: release enablement, archival support, CI/CD refinements, and branding

[markurtz]

Description

This PR introduces a substantial set of features, fixes, and documentation updates to prepare GitVersioned for its initial release. The key changes include:

• Archival Versioning Support: Implemented a robust fallback mechanism using .git_archival.txt. This enables GitVersioned to resolve version information for source code bundles (like GitHub ZIP downloads) when the .git directory is absent.
• CI/CD Pipeline Refinements: Finalized the release infrastructure for stable and nightly builds. This includes automated GitHub release generation, PyPI publishing via OIDC, artifact attestations, and a fix for the TruffleHog scan error where BASE and HEAD commits were identical.
• dirty_ignore Setting: Enhanced the configuration model to allow users to specify file patterns that should be ignored during the repository dirty-state check.
• Git Utility Refactoring: Standardized git reference modeling by consolidating metadata into GitReference and configuring default values (such as distance_from_head default maximums) for edge cases where commit histories are shallow or missing.
• Project Branding & Documentation: Introduced new light and dark mode project assets (icons, logos, and user flow diagrams). Extensively overhauled the README.md and MkDocs site to feature the new branding, document the archive fallback functionality, and polish the general project presentation.
• Test Coverage Expansion: Added parameterized testing for the archival resolution pathway and updated test cases to account for dirty_ignore validations.

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

• Verified that the _security.yml workflow completes successfully without TruffleHog reference errors.
• Added automated unit tests (tests/unit/test_versioning.py) explicitly validating the _resolve_archive fallback pathway.
• Validated dirty_ignore behaviors locally by verifying that listed untracked or modified files do not trigger the dirty state flag.
• Ensured all test suites complete successfully using hatch run test:all.
• Verified the MkDocs build via hatch run docs:build to confirm new assets and configurations load correctly.

Related Issues

• Fixes # (Add any relevant issue numbers if applicable)

Screenshots / Visuals (if applicable)

(Review the updated MkDocs documentation locally to see the newly integrated logo-light/logo-dark and user-flow-light/user-flow-dark diagrams.)

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

• "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

[github-actions]

CI Development Pipeline Status

✅ Pipeline: Completed successfully. View Run Details

[Copilot]

Pull request overview

This PR prepares GitVersioned for an initial release by adding archive-based version resolution (for ZIP/source bundles without a .git directory), refactoring Git metadata into a unified GitReference model, and updating CI/CD plus documentation/branding.

Changes:

• Added archive fallback support via .git_archival.txt/.gitattributes and extended version-resolution logic to use it when git metadata is unavailable.
• Refactored git metadata models into GitReference, updated templates to emit richer git metadata, and expanded unit/e2e coverage.
• Refined GitHub Actions workflows for nightly/release pipelines and refreshed docs/MkDocs branding assets.

Reviewed changes

Copilot reviewed 26 out of 42 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/unit/utils/test_git.py	Updates unit tests for GitReference and new git log parsing/commit counting behavior.
tests/unit/test_versioning.py	Refactors/expands version-resolution tests, including archive fallback cases.
tests/e2e/test_builds.py	Adds an e2e build test that simulates an archive build (no .git).
src/gitversioned/versioning.py	Implements multi-source iteration, archive fallback parsing, dirty-ignore handling, and updated function-source behavior.
src/gitversioned/utils/git.py	Introduces GitReference and updates repository iterators/parsing (commits/tags/branches) and commit counting.
src/gitversioned/utils/init.py	Re-exports GitReference and removes old git metadata exports.
src/gitversioned/templates/release.py.template	Switches templates to use ref and emits additional git metadata fields.
src/gitversioned/templates/dev.py.template	Switches templates to use ref and emits additional git metadata fields.
src/gitversioned/settings.py	Adds regex_version, archive regex/config, and dirty_ignore setting.
scratch2.py	Removes scratch helper script.
scratch.py	Removes scratch helper script.
README.md	Updates positioning and adds archive-support quickstart instructions.
mkdocs.yml	Configures MkDocs logo/favicon branding.
docs/index.md	Updates docs landing page with branding assets and diagrams.
docs/guides/setuptools.md	Adds note about ZIP downloads and archive fallback.
docs/guides/hatchling.md	Adds note about ZIP downloads and archive fallback.
docs/guides/configuration.md	Documents archive fallback and dirty_ignore.
docs/guides/concepts.md	Documents archive fallback behavior in conceptual flow.
docs/getting-started/quickstart.md	Adds “Configure Archive Support” steps.
docs/assets/branding/logo-light.svg	Replaces placeholder with new light logo asset.
docs/assets/branding/logo-dark.svg	Replaces placeholder with new dark logo asset.
docs/assets/branding/logo-blue.svg	Adds blue logo variant asset.
docs/assets/branding/icon-white.svg	Adds white icon asset.
docs/assets/branding/icon-blue.svg	Adds blue icon asset.
docs/assets/branding/icon-black.svg	Adds black icon asset.
.pre-commit-config.yaml	Removes check-added-large-files hook.
.github/workflows/release.yml	Refines release docs aliasing and publishing workflow usage.
.github/workflows/nightly.yml	Adds change-detection gating and OIDC permissions for nightly pipeline stages.
.github/workflows/_security.yml	Removes TruffleHog base/head args to avoid identical ref issues.
.github/workflows/_publish.yml	Switches to OIDC publishing, adds attestations, and creates GitHub Releases on tags.
.gitattributes	Enables export-subst for .git_archival.txt.
.git_archival.txt	Adds archive metadata template for version/metadata fallback.

Comments suppressed due to low confidence (1)

tests/unit/utils/test_git.py:296

• test_commits patches _ensure_valid_repository and _stream_command, but GitRepository.commits now calls self.commit_count, which triggers git subprocess calls via is_available/_execute_command. This makes the unit test environment-dependent. Patch GitRepository.commit_count (or is_available/_execute_command) in this test to keep it hermetic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

CI Development Pipeline Status

✅ Pipeline: Completed successfully. View Run Details