Remove test file

VERSION_FIELD.md

@@ -0,0 +1,130 @@
+# Version Field Behavior
+
+## Overview
+
+The `version` field in frontmatter is derived from git metadata with tag preference.
+
+## Priority
+
+1. **Latest commit tag** (if exists)
+2. **Short commit hash** (7 characters) as fallback
+
+## Examples
+
+### With Git Tag
+
+**Git history:**
+```
+853ace5 (tag: v1.0.0) Add comparison test file
+```
+
+**Resulting frontmatter:**
+```yaml
+---
+version: v1.0.0
+---
+```
+
+### Without Git Tag
+
+**Git history:**
+```
+0463d73 Add file without tag
+```
+
+**Resulting frontmatter:**
+```yaml
+---
+version: 0463d73
+---
+```
+
+## Implementation Details
+
+### Repository Module
+The `get_file_history()` method in `core/repository.py` extracts:
+- `latest_hash`: The most recent commit hash for the file
+- `latest_tag`: The tag associated with the latest commit (if any)
+
+```python
+# Get tag for latest commit if any
+latest_tag = ''
+if latest_hash:
+    result = subprocess.run(
+        ['git', 'describe', '--tags', '--exact-match', latest_hash],
+        ...
+    )
+    latest_tag = result.stdout.strip() if result.returncode == 0 else ''
+```
+
+### Processor Module
+The `_get_heuristic_value()` method in `core/processor.py` prefers the tag:
+
+```python
+elif field == 'version':
+    # Prefer latest tag, fallback to short hash
+    latest_tag = git_info.get('latest_tag', '')
+    if latest_tag:
+        return latest_tag
+    latest_hash = git_info.get('latest_hash', '')
+    return latest_hash[:7] if latest_hash else ''
+```
+
+## Use Cases
+
+### Semantic Versioning
+Tag commits with semantic versions:
+```bash
+git tag -a v2.1.0 -m "Release 2.1.0"
+```
+
+Files modified in this commit will have:
+```yaml
+version: v2.1.0
+```
+
+### Development Builds
+Commits without tags automatically get short hash:
+```yaml
+version: a3f9c21
+```
+
+## Best Practices
+
+1. **Tag releases:** Use semantic versioning for releases
+   ```bash
+   git tag -a v1.0.0 -m "Release 1.0.0"
+   git tag -a v1.1.0 -m "Release 1.1.0"
+   ```
+
+2. **Let development builds use hashes:** Don't tag every commit
+
+3. **Consistency:** Use a consistent tagging scheme
+   - `v1.0.0` (recommended)
+   - `1.0.0`
+   - `release-1.0.0`
+
+## Verification
+
+Check what version will be used:
+```bash
+# For a specific file
+git log -1 --oneline path/to/file.md
+
+# Check if commit has a tag
+git describe --tags --exact-match <commit-hash>
+```
+
+## Limitations
+
+- Only exact tag matches are used (`--exact-match`)
+- Annotated tags and lightweight tags both work
+- If multiple tags point to same commit, git chooses one
+- Tags must exist locally (not just on remote)
+
+## Migration Notes
+
+If upgrading from previous version where only short hash was used:
+- Re-run madomeda to update version fields
+- Files on tagged commits will switch from hash to tag
+- Use `--whatif` to preview changes