# .clinerules - Memory Bank for extended-data-types

## Project Overview
Python library providing extended functionality for data types (YAML, JSON, TOML, HCL2, etc.)

## Core Architecture Decisions

### Release Process (2025-11-23)
**Decision**: Single-workflow, tag-only release process
**Rationale**:
- Branch protection on `main` requires status checks before pushes
- Creating version bump commits and pushing them triggers branch protection errors
- Running CI twice (once for PR, once for version bump) is inefficient
**Implementation**:
- Consolidated CI and Release workflows into single `.github/workflows/ci.yml`
- Release job runs after all tests pass on `main` branch pushes
- `semantic-release` configured with `commit: false`, `push: false`, `tag: true`
- Creates Git tags and GitHub releases WITHOUT committing version bumps back to repo
- Version numbers in source files remain informational only; PyPI package version comes from git tags
**Artifacts**:
- Build job creates "Packages" artifact (unsigned, for testing)
- Release job creates "Packages-signed" artifact (signed with attestations, for PyPI)

### Workflow Structure
```
PR merged to main
    ↓
CI Workflow triggers
    ├── build-package (creates "Packages" artifact)
    ├── tests (parallel, all Python versions)
    ├── typechecking
    ├── linting
    ├── coverage
    ↓ (all pass)
    ├── release (only on main)
    │   ├── semantic-release (calculates version, creates tag)
    │   ├── publish GitHub release
    │   └── build signed packages ("Packages-signed" artifact)
    └── publish (PyPI)
        └── upload signed packages
```

## Critical Patterns

### No Version Bump Commits
- We do NOT create version bump commits
- We do NOT create PRs for version bumps
- Version in source files may lag behind releases (this is intentional)
- Git tags are the source of truth for versions

### Artifact Naming
- Default build: "Packages" (for CI testing)
- Signed build: "Packages-signed" (for PyPI publishing)
- Always use `upload-name-suffix: "-signed"` in release job to avoid conflicts

## Dependencies
- `python-semantic-release` v9.17.0: Version calculation and release creation
- `hynek/build-and-inspect-python-package@v2`: Package building with signed attestations
- `pypa/gh-action-pypi-publish`: PyPI publishing

## Environment Variables
- `GH_TOKEN` or `GITHUB_TOKEN`: GitHub API access (use `GITHUB_JBCOM_TOKEN` for org access)

## Common Issues
1. **Branch protection errors**: Don't try to push commits to main; use tags only
2. **Artifact conflicts**: Always use unique names for multiple build steps
3. **Version drift**: Source file versions may not match PyPI; this is expected

## References
- Original issue: https://github.com/jbcom/extended-data-types/actions/runs/19615176677/job/56166714816
- PR: https://github.com/jbcom/extended-data-types/pull/41
