half_orm development Framework.

These details have not been verified by PyPI

Project links

Homepage

Project description

half-orm-dev

WARNING! half-orm-dev is in alpha development phase!

Git-centric patch management and database versioning for half-orm projects

Modern development workflow for PostgreSQL databases with automatic code generation, semantic versioning, and production-ready deployment system.

📖 Description

half-orm-dev provides a complete development lifecycle for database-driven applications:

Git-centric workflow: Patches stored in Git branches and release files
Semantic versioning: Automatic version calculation (patch/minor/major)
Code generation: Python classes auto-generated from schema changes
Safe deployments: Automatic backups, rollback support, validation
Team collaboration: Distributed locks, branch notifications, conflict prevention
Test-driven development: Systematic validation before any integration

Perfect for teams managing evolving PostgreSQL schemas with Python applications.

✨ Features

🔧 Development

Patch-based development: Isolated branches for each database change
Automatic code generation: half-orm Python classes created from schema
Complete testing: Apply patches with full release context
Conflict detection: Distributed locks prevent concurrent modifications

🧪 Test-Driven Development & Validation

Systematic Testing Before Integration

half-orm-dev enforces a test-first approach that guarantees code quality:

1. Validation on Temporary Branches

# When closing a patch, tests run FIRST
# You must be on the patch branch
git checkout ho-patch/456-user-auth
half_orm dev patch merge

# What happens behind the scenes:
# 1. Creates temp-valid-1.3.6 branch
# 2. Merges ALL release patches + new patch
# 3. Runs pytest tests/
# 4. If merge and tests PASS → merges patch branch into release branch; changes patch status to "staged" in TOML and commits
# 5. If anything FAILS → nothing committed (temp branch is deleted)

2. No Integration Without Tests

❌ BLOCKED: Patches cannot be added to releases if anything fails
✅ SAFE: Only validated code reaches stage/rc/production
🔒 GUARANTEED: Every release is testable before deployment

3. Business Logic Testing (TDD Best Practice)

# Your business logic is fully testable
# Example: tests/test_user_authentication.py

def test_user_creation():
    """Test user creation through half-orm models."""
    user = User(
        username='john',
        email='john@example.com'
    ).ho_insert()

    assert user.id is not None
    assert user.username == 'john'

def test_invalid_email_rejected():
    """Test validation prevents invalid emails."""
    with pytest.raises(ValidationError):
        User(username='john', email='invalid').ho_insert()

4. Full Release Context Testing

# Test your patch with ALL previous patches
half_orm dev patch apply

# What happens:
# 1. Restores DB to production state
# 2. Applies all RC patches (if any)
# 3. Applies all stage patches
# 4. Applies YOUR patch in correct order
# 5. Generates code
# → Your tests run in realistic production-like environment

5. Workflow Integration

┌───────────────────────────────────────────────────────────────────┐
│ Development Cycle with Test Validation                            │
├───────────────────────────────────────────────────────────────────┤
│ 1. Create patch                                                   │
│ 2. Write tests FIRST (TDD)                                        │
│ 3. Implement feature                                              │
│ 4. Run tests locally: pytest                                      │
│ 5. Add to release → AUTOMATIC VALIDATION                          │
│    ├─ temp-valid branch created                                   │
│    | ├─ All patches merged                                        │
│    | └─ pytest runs automatically                                 │
│    └─ Only commits if everything is OK                            │
│ 6. Promote to RC → Tests validated again, code merged on ho-prod  │
│ 7. Deploy to prod → Tested code only                              │
└───────────────────────────────────────────────────────────────────┘

Benefits:

✅ Catch Integration Issues Early: Test interactions between patches
✅ Prevent Regressions: Existing tests protect against breaking changes
✅ Document Behavior: Tests serve as executable specifications
✅ Safe Refactoring: Change implementation with confidence
✅ Team Collaboration: Clear expectations for code quality

📦 Release Management

Semantic versioning: patch/minor/major increments
Release candidates: RC validation before production
Sequential promotion: stage → rc → production workflow
Branch cleanup: Automatic deletion after RC promotion
Test validation: Automated testing at every promotion step

🚀 Production

Safe upgrades: Automatic database backups before changes
Incremental deployment: Apply releases sequentially
Dry-run mode: Preview changes before applying
Version tracking: Complete release history in database
Rollback support: Automatic rollback on failures

👥 Team Collaboration

Distributed locks: Prevent concurrent ho-prod modifications
Branch notifications: Alert developers when rebase needed
Multiple stages: Parallel development of different releases
Git-based coordination: No external tools required

🚀 Installation

Prerequisites

Python 3.8+
PostgreSQL 12+
Git
half-orm (pip install half-orm)

Install

pip install half-orm-dev

Verify Installation

half_orm dev --help

📖 Quick Start

Initialize New Project

# Create project with database
half_orm dev init myproject --database mydb

# Navigate to project
cd myproject

Clone Existing Project

# Clone from Git
half_orm dev clone https://github.com/user/project.git

# Navigate to project
cd project

First Patch (TDD Development)

# First, create a release integration branch
half_orm dev release new minor  # Creates ho-release/0.1.0

# Now create patch (automatically added to candidates)
half_orm dev patch create 1-users
# → Auto-added to 0.1.0-patches.toml as "candidate"

# Add schema changes
echo "CREATE TABLE users (id uuid PRIMARY KEY DEFAULT gen_random_uuid(), username TEXT NOT NULL);" > Patches/1-users/01_users.sql

# Apply patch - this generates Python code AND test directory structure
half_orm dev patch apply
# → Restores database
# → Applies SQL patches
# → Generates Python classes (mydb/public/user.py)
# → Creates test directory structure (tests/public/user/)

# Now write business logic tests (TDD approach)
# IMPORTANT: Test business logic, NOT ORM operations like ho_insert()
cat > tests/public/user/test_user_business_logic.py << 'EOF'
from mydb.public.user import User

def test_user_creation_with_valid_data():
    """Test creating a user with valid business logic."""
    # Assuming you implement a create() business method
    user = User.create(username='alice')
    assert user['username'] == 'alice'
    assert user['id'] is not None

def test_user_creation_rejects_empty_username():
    """Test business validation."""
    # Should raise an error if you implement validation
    with pytest.raises(ValueError):
        User.create(username='')
EOF

# Implement business logic in your User class
cat >> mydb/public/user.py << 'EOF'

@classmethod
def create(cls, username: str):
    """Business logic for creating a user."""
    if not username or not username.strip():
        raise ValueError("Username cannot be empty")
    return cls(username=username).ho_insert()
EOF

# Run tests
pytest

# Commit your work
git add .
git commit -m "Add users table with business logic and tests"

# Close patch - integrate to release (automatic validation runs here!)
# You must be on the patch branch
git checkout ho-patch/1-users
half_orm dev patch merge
# → Status changed to "staged" in TOML
# → Tests validated automatically

💻 Development Workflow

Vision: Git-Flow Release Management

The workflow follows a Git-Flow approach with dedicated integration branches (ho-release/X.Y.Z) that serve as test sandboxes before production.

Motivation:

Patches are visible and testable on ho-release/X.Y.Z before production
ho-prod remains stable and contains only validated versions (RC or production)
Workflow compatible with GitLab/GitHub (milestones, merge requests, issues)
No need to create RC just to make a patch accessible

Complete Cycle: Patch → Release → Deploy

┌─────────────────────────────────────────────────────────────────┐
│ DEVELOPMENT (ho-release/X.Y.Z branch)                           │
├─────────────────────────────────────────────────────────────────┤
│ 1. release new <level>     Create ho-release/X.Y.Z              │
│ 2. patch create <id>          Create patch (auto in candidates)    │
│ 3. patch apply             Apply & test changes                 │
│ 4. patch merge             Merge into ho-release (TESTS!)       │
│                            (run from ho-patch/<id> branch)      │
│                                                                 │
│ RELEASE PROMOTION                                               │
│ 5. release promote rc      Create RC (tags ho-release branch)   │
│ 6. release promote prod    Merge to ho-prod + deploy            │
│                                                                 │
│ PRODUCTION DEPLOYMENT                                           │
│ 7. update                  Check available releases             │
│ 8. upgrade                 Apply on production servers          │
│                                                                 │
│ HOTFIX WORKFLOW (urgent fixes)                                  │
│ 9. release hotfix          Reopen production version            │
│ 10. patch create/close        Same workflow on hotfix branch       │
│ 11. release promote hotfix Deploy as vX.Y.Z-hotfixN             │
└─────────────────────────────────────────────────────────────────┘

Workflow Details

Concepts: Release Files and Patch States

Release Files:

.hop/releases/
├── 0.17.0-patches.toml     # Patches in development (TOML format with status)
├── 0.17.0-rc1.txt          # First Release Candidate (snapshot)
├── 0.17.0-rc2.txt          # Second RC (with fixes, snapshot)
├── 0.17.0.txt              # Production version (snapshot)
├── 0.17.0-hotfix1.txt      # Urgent production fix (snapshot)
└── 0.18.0-patches.toml     # Next release in progress

TOML Patches File Format (0.17.0-patches.toml):

[patches]
"1-auth" = "candidate"    # In development
"2-api" = "candidate"     # In development
"3-ui" = "staged"         # Integrated, awaiting RC
"4-tests" = "staged"      # Integrated, awaiting RC

Patch States:

Candidate: Assigned to release, in development ("candidate" in TOML)
Staged: Integrated in ho-release/X.Y.Z, awaiting promotion ("staged" in TOML)
Released: Included in deployed production version (in X.Y.Z.txt snapshot)

Analogy with GitLab/GitHub:

half-orm state	File	GitLab/GitHub
`release new`	Creates `-patches.toml`	Create milestone
`patch create` (on ho-release)	Adds to TOML as "candidate"	Create issue assigned to milestone
Candidate	`"patch-id" = "candidate"` in TOML	Open issue assigned to milestone
`patch merge`	Changes to `"staged"` in TOML	Merge MR and close issue
Stage	`"patch-id" = "staged"` in TOML	Closed issue in milestone
`release promote rc`	Creates `-rcN.txt` snapshot	Create pre-release
RC	`-rcN.txt`	GitHub pre-release
`release promote prod`	Creates `X.Y.Z.txt`, deletes TOML	Create stable release
Production	`X.Y.Z.txt`	Stable release

Step 1: Create a New Release

half_orm dev release new minor
# → Detects current production version (e.g., 0.16.0)
# → Calculates next minor version: 0.17.0
# → Creates branch ho-release/0.17.0 from ho-prod
# → Creates .hop/releases/0.17.0-patches.toml (empty TOML file)
# → Commits and pushes to reserve version globally
# → Automatically switches to ho-release/0.17.0

Output:

✅ Release created successfully!

  Version:          0.17.0
  Release branch:   ho-release/0.17.0
  Patches file:     .hop/releases/0.17.0-patches.toml

📝 Next steps:
  1. Create patches: half_orm dev patch create <patch_id>
  2. Close patches: git checkout ho-patch/<patch_id> && half_orm dev patch merge
  3. Promote to RC: half_orm dev release promote rc

ℹ️  Patches will be merged into ho-release/0.17.0 for integration testing

Step 2: Create a Candidate Patch

Prerequisites: Must be on ho-release/0.17.0 branch

git checkout ho-release/0.17.0
half_orm dev patch create 6-feature-x
# → Auto-detects version 0.17.0 from current branch
# → Creates ho-patch/6-feature-x from ho-release/0.17.0
# → Adds 6-feature-x to 0.17.0-patches.toml as "candidate"
# → Switches to ho-patch/6-feature-x

Output:

✓ Created patch branch: ho-patch/6-feature-x
✓ Created patch directory: Patches/6-feature-x/
✓ Added to candidates: .hop/releases/0.17.0-patches.toml
✓ Switched to branch: ho-patch/6-feature-x

📝 Next steps:
  1. Add SQL/Python files to Patches/6-feature-x/
  2. Run: half_orm dev patch apply
  3. Test your changes
  4. Run: half_orm dev patch merge (already on ho-patch/6-feature-x)

Step 3: Develop and Test (TDD Approach)

# Apply patch (on ho-patch/* branch)
half_orm dev patch apply
# → Restores database from production state
# → Applies all release patches + current patch
# → Generates Python code
# → Ready for testing

# FIRST: Write tests
cat > tests/public/users/test_users_feature.py << 'EOF'
def test_feature():
    # Your test here
    assert True
EOF

# Run tests
pytest

# Commit your work
git add .
git commit -m "Implement feature with tests"

Step 4: Close Patch (Integrate to Release)

# Ensure you're on the patch branch
git checkout ho-patch/6-feature-x

half_orm dev patch merge
# Complete workflow:
# → Detects version from 0.17.0-patches.toml
# → Validates ho-patch/6-feature-x exists
# → Creates temporary validation branch
# → Merges ho-patch/6-feature-x into temp branch
# → Restores database and applies all patches
# → Runs tests (pytest)
# → If PASS: Merges into ho-release/0.17.0
# → Changes 6-feature-x from "candidate" to "staged" in TOML
# → Deletes branch ho-patch/6-feature-x
# → Commits and pushes changes
# → Notifies other candidate patches to sync

Output:

✓ Patch closed successfully!

  Patches file:    .hop/releases/0.17.0-patches.toml
  Patch status:    6-feature-x → "staged"
  Tests passed:    ✓
  Notified:        2 active branch(es)

📝 Next steps:
  • Other developers: git pull && git merge ho-release/0.17.0
  • Continue development: half_orm dev patch create <next_patch_id>
  • Promote to RC: half_orm dev release promote rc

Important: patch merge replaces the old patch add command. The semantics are different:

OLD: patch add = "I add my validated patch to release" (from ho-prod)
NEW: patch merge = "I close my work, it's integrated in release" (merge into ho-release)

Step 5: Synchronize with Other Integrated Patches

When another patch is integrated in the release, candidate patches must update:

git fetch origin
git merge origin/ho-release/0.17.0

Step 6: Promote to RC

Sequentiality Rule: Only the smallest version in preparation can be promoted to RC. This guarantees sequential release order.

Example: If releases 0.17.1, 0.18.0 and 1.0.0 are in preparation, only 0.17.1 can be promoted to RC.

half_orm dev release promote rc
# Complete workflow:
# → Auto-detects smallest version with -patches.toml containing staged patches
# → Verifies it's sequential (follows last prod/RC)
# → Automatically switches to ho-release/X.Y.Z
# → Finds next RC number (rc1, rc2, etc.)
# → Creates tag vX.Y.Z-rc1 on ho-release/X.Y.Z (NOT on ho-prod!)
# → Creates snapshot .hop/releases/X.Y.Z-rc1.txt with staged patches
# → Resets staged patches to candidates in TOML for potential fixes
# → Commits and pushes

Output:

✓ Success!

  Version:  0.17.0
  Tag:      v0.17.0-rc1
  Branch:   ho-release/0.17.0

📝 Next steps:
  • Test RC thoroughly
  • Deploy to production: half_orm dev release promote prod

Important Notes:

Tag is created on ho-release/0.17.0, NOT on ho-prod
Command auto-detects which version to promote (smallest)
Cannot "skip" a version: if 0.17.0 isn't in prod, can't promote 0.18.0

Step 7: Promote to Production

Sequentiality Rule: Only the smallest version in preparation (with a stage file) can be promoted to production.

half_orm dev release promote prod
# Complete workflow:
# → Auto-detects smallest version with -patches.toml containing staged patches
# → Verifies strict sequentiality (0.17.0 must follow last prod)
# → Automatically switches to ho-prod
# → Merges ho-release/0.17.0 into ho-prod (integrates patch code)
# → Restores database and applies all staged patches from TOML
# → Generates .hop/model/schema-0.17.0.sql and metadata-0.17.0.sql
# → Updates symlink .hop/model/schema.sql → schema-0.17.0.sql
# → Creates .hop/releases/0.17.0.txt snapshot with all patches
# → Deletes .hop/releases/0.17.0-patches.toml (no longer needed)
# → Preserves .hop/releases/0.17.0-rc*.txt for history (if any)
# → Creates tag v0.17.0 on ho-prod
# → Deletes branch ho-release/0.17.0 (mission complete)
# → Commits and pushes

Output:

✓ Success!

  Version:          0.17.0
  Tag:              v0.17.0
  Branches deleted: ho-release/0.17.0

📝 Next steps:
  • Deploy to production servers
  • Start next cycle: half_orm dev release new minor

Important Notes:

This is when patch code is actually merged into ho-prod, not before
Command auto-detects smallest version with stage file
Always uses stage file: RC files are preserved for history but not used for promotion
RC is optional: Can promote directly from stage to production without creating RC
Sequentiality is strictly enforced: impossible to promote 0.18.0 if 0.17.0 isn't already in prod

Step 8/9: Production Upgrade

# On production server (automatically pulls from origin)
# Check available releases
half_orm dev update

# Apply upgrade (with automatic backup and git pull)
half_orm dev upgrade

Hotfix Workflow (Urgent Production Fixes)

Scenario: Critical bug discovered in production (v0.17.0) while new release (v0.18.0) is already in development. Production needs fixing immediately without waiting for v0.18.0.

Step 1: Reopen Production Version

half_orm dev release hotfix
# Workflow:
# → Detects production version from model/schema.sql (e.g., 0.17.0)
# → Verifies tag v0.17.0 exists
# → Reopens branch ho-release/0.17.0 from tag v0.17.0
# → Automatically switches to ho-release/0.17.0

Output:

✓ Reopened ho-release/0.17.0 from v0.17.0
✓ Ready for hotfix patches

📝 Next steps:
  1. half_orm dev patch create <patch_id>
  2. git checkout ho-patch/<patch_id> && half_orm dev patch merge
  3. half_orm dev release promote hotfix

Important Note: This is a break from sequential workflow as we now have two active release branches simultaneously (ho-release/0.17.0 and ho-release/0.18.0).

Step 2: Create and Integrate Hotfix Patch

The workflow is identical to normal workflow:

# On ho-release/0.17.0
half_orm dev patch create 999-critical-security-fix
# ... develop ...
half_orm dev patch apply
# ... test ...
git checkout ho-patch/999-critical-security-fix
half_orm dev patch merge

Step 3: Promote Hotfix to Production

Important: Cannot use promote prod as tag v0.17.0 already exists!

git checkout ho-prod
half_orm dev release promote hotfix
# Hotfix-specific workflow:
# → Detects hotfix context (tag vX.Y.Z already exists)
# → Finds next hotfix number (hotfix1, hotfix2, etc.)
# → Merges ho-release/0.17.0 into ho-prod
# → Generates model/schema-0.17.0-hotfix1.sql and metadata-0.17.0-hotfix1.sql
# → Updates symlink model/schema.sql → schema-0.17.0-hotfix1.sql
# → Creates releases/0.17.0-hotfix1.txt with patch list
# → Creates tag v0.17.0-hotfix1 on ho-prod
# → Deletes branch ho-release/0.17.0
# → Commits and pushes

Output:

✓ Hotfix deployed!

  Version:  0.17.0-hotfix1
  Tag:      v0.17.0-hotfix1
  Patches:  999-critical-security-fix

📝 Next steps:
  • Deploy to production servers immediately
  • Sync other releases: git checkout ho-release/0.18.0 && git merge ho-prod

Step 4: Sync Other In-Progress Releases

If a release is in development (e.g., 0.18.0), it must integrate the hotfix:

git checkout ho-release/0.18.0
git merge ho-prod
# Resolve any conflicts
git push origin ho-release/0.18.0

This guarantees the bugfix won't be lost in the next release.

📖 Command Reference

NOTE: use half_orm dev command --help for detailed help on each command

Init & Clone

# Create new project
half_orm dev init <package_name> --database <db_name>

# Clone existing project (automatically pulls from origin)
half_orm dev clone <git_origin>

Patch Commands

# Create new patch (must be on ho-release/* branch)
half_orm dev patch create <patch_id> [-d "description"] [--before <other_patch_id>]
# → Patches are ordered in the TOML file (insertion order = application order)
# → Use --before to insert a patch before an existing one
# → Order matters: patches are applied sequentially

# Apply current patch (must be on ho-patch/* branch)
half_orm dev patch apply

# Close patch - integrate to release (AUTOMATIC VALIDATION!)
# Must be on ho-patch/* branch
half_orm dev patch merge

Patch Ordering:

Patches are stored in the TOML file in insertion order
This order determines the application sequence (critical for dependencies)
Use --before option to insert a patch at a specific position
Example: If patch B depends on patch A, ensure A is ordered before B

Release Commands

# Prepare next release (patch/minor/major)
# Creates ho-release/X.Y.Z branch + candidates.txt + stage.txt
half_orm dev release new patch
half_orm dev release new minor
half_orm dev release new major

# Promote stage to RC (automatically pushes)
# Tags ho-release/X.Y.Z, renames stage → rc
half_orm dev release promote rc

# Promote RC to production (automatically pushes)
# Merges ho-release/X.Y.Z → ho-prod, creates tag
half_orm dev release promote prod

# Reopen production version for hotfix
half_orm dev release hotfix

# Promote hotfix to production
half_orm dev release promote hotfix

Production Commands

# Fetch available releases (automatically pulls from origin)
half_orm dev update

# Apply releases to production (automatically pulls from origin)
half_orm dev upgrade [--to-release X.Y.Z]

# Dry run (simulate upgrade)
half_orm dev upgrade --dry-run

🎯 Common Patterns

Pattern 1: Planned Development with Integration Branch

# Start by creating release integration branch
half_orm dev release new minor  # Creates ho-release/0.17.0

# Now on ho-release/0.17.0, create patch
half_orm dev patch create 123-add-users
# → Auto-added to 0.17.0-candidates.txt

# Add SQL/Python files
echo "CREATE TABLE users (id SERIAL PRIMARY KEY, username TEXT);" > Patches/123-add-users/01_users.sql

# Write tests
cat > tests/public/test_public_users.py << 'EOF'
def test_user_creation():
    user = User(username='alice').ho_insert()
    assert user['username'] == 'alice'
EOF

# Apply and test
half_orm dev patch apply
pytest  # Tests should pass

# Commit your work
git add .
git commit -m "Implement users table with tests"

# Close patch - integrate to release (tests validated automatically!)
git checkout ho-patch/123-add-users
half_orm dev patch merge
# → Status changed to "staged" in TOML
# → Tests run automatically before integration

Pattern 2: Team Collaboration on Same Release

# Integration Manager: Create release
half_orm dev release new minor  # Creates ho-release/0.17.0

# Developer A: Working on feature
git checkout ho-release/0.17.0
half_orm dev patch create 456-dashboard
# → Added to 0.17.0-patches.toml as candidate
# ... develop and test ...
git checkout ho-patch/456-dashboard
half_orm dev patch merge
# → Status changed to "staged" in TOML

# Developer B: Must sync with A's changes first
git checkout ho-release/0.17.0
git pull origin ho-release/0.17.0  # Get A's integrated changes

# Then create patch
half_orm dev patch create 789-reports
# → Added to 0.17.0-patches.toml as candidate
# ... develop and test ...
git merge origin/ho-release/0.17.0  # Sync again before closing
git checkout ho-patch/789-reports
half_orm dev patch merge
# → Tests run with 456 + 789 together!

# All patches validated together in stage

Pattern 3: Parallel Development of Different Releases

# Parallel development of different versions
# 1. Create multiple release branches
half_orm dev release new minor  # Creates 0.18.0
half_orm dev release new patch  # Creates 0.17.1

# 2. Add patches to specific versions
git checkout ho-release/0.17.1
half_orm dev patch create 123-hotfix
git checkout ho-patch/123-hotfix
half_orm dev patch merge

git checkout ho-release/0.18.0
half_orm dev patch create 456-feature
git checkout ho-patch/456-feature
half_orm dev patch merge

# 3. Sequential promotion (must promote 0.17.1 before 0.18.0)
half_orm dev release promote rc   # Auto-promotes 0.17.1 (smallest)
# ... validate ...
half_orm dev release promote prod  # 0.17.1 to production
# Now can promote 0.18.0
half_orm dev release promote rc   # Auto-promotes 0.18.0

Pattern 4: Incremental RC (Fix Issues)

# RC1 has issues discovered in testing
half_orm dev release promote rc  # Creates 0.17.0-rc1
# → Creates rc1.txt snapshot
# → Staged patches remain in TOML

# Found bug in testing, create fix patch
git checkout ho-release/0.17.0  # Back to integration branch
half_orm dev patch create 999-rc1-fix
# → Added to 0.17.0-patches.toml as candidate
half_orm dev patch apply
# ... fix and test ...

# Close patch - changes status to staged
git checkout ho-patch/999-rc1-fix
half_orm dev patch merge
# → Status changed to "staged" in TOML
# → Validated automatically

# Promote again (creates rc2, automatically pushes)
half_orm dev release promote rc  # Creates 0.17.0-rc2
# → Creates rc2.txt snapshot with all staged patches
# → Staged patches remain in TOML

# Repeat until RC passes all validation

Pattern 5: Hotfix on Production

# Bug discovered in production (v0.17.0)
# New release (v0.18.0) already in development

# Reopen production version
half_orm dev release hotfix
# → Reopens ho-release/0.17.0 from tag v0.17.0
# → Creates 0.17.0-patches.toml for hotfix patches

# Same workflow as normal patch
half_orm dev patch create 999-critical-fix
# → Added to 0.17.0-patches.toml as candidate (with # HOTFIX marker)
half_orm dev patch apply
# ... fix and test ...
git checkout ho-patch/999-critical-fix
half_orm dev patch merge
# → Status changed to "staged" in TOML

# Promote as hotfix
git checkout ho-prod
half_orm dev release promote hotfix
# → Creates v0.17.0-hotfix1 tag
# → Creates 0.17.0-hotfix1.txt file
# → Merges into ho-prod

# Sync other in-progress releases
git checkout ho-release/0.18.0
git merge ho-prod  # Integrate the hotfix

Pattern 6: Production Deployment

# On production server (commands automatically pull from origin)

# Check available releases
half_orm dev update

# Simulate upgrade
half_orm dev upgrade --dry-run

# Apply upgrade (creates backup automatically, pulls from origin)
half_orm dev upgrade

# Or apply specific version
half_orm dev upgrade --to-release 1.4.0

🏗️ Architecture

Branch Strategy

ho-prod (main production)
│
├── ho-release/0.17.0 (integration branch, deleted after prod promotion)
│   ├── ho-patch/6-feature-x    (temporary, deleted after close)
│   ├── ho-patch/7-bugfix-y     (temporary, deleted after close)
│   └── ho-patch/8-auth-z       (temporary, deleted after close)
│
└── ho-release/0.18.0 (next version in parallel)
    └── ho-patch/10-new-api     (temporary, deleted after close)

Branch types:

ho-prod: Main production branch (source of truth, stable)
ho-release/X.Y.Z: Integration branch for version X.Y.Z (temporary, deleted after prod promotion)
ho-patch/*: Patch development branches created from ho-release/* (temporary, deleted after close)

Branch Lifecycle:

release new creates ho-release/X.Y.Z from ho-prod
patch create creates ho-patch/ID from ho-release/X.Y.Z
patch merge merges ho-patch/ID into ho-release/X.Y.Z and deletes ho-patch/ID
release promote prod merges ho-release/X.Y.Z into ho-prod and deletes ho-release/X.Y.Z

Exception - Hotfix Branches:

release hotfix reopens ho-release/X.Y.Z from existing tag vX.Y.Z
Multiple ho-release/* branches can exist temporarily (prod version + dev version)
After promote hotfix, the hotfix branch is deleted

Release Files

.hop/releases/
├── 0.17.0-patches.toml    (patches with status: candidate/staged, mutable)
├── 0.17.0-rc1.txt         (first RC snapshot, immutable)
├── 0.17.0-rc2.txt         (fixes from rc1 snapshot, immutable)
├── 0.17.0.txt             (production snapshot, immutable)
├── 0.17.0-hotfix1.txt     (hotfix on production snapshot, immutable)
└── 0.18.0-patches.toml    (next version patches)

File lifecycle (normal workflow):

patch create → X.Y.Z-patches.toml (patch added as "candidate")
                    ↓
patch merge → X.Y.Z-patches.toml (status changed to "staged")
                    ↓
                    ├─→ promote rc → X.Y.Z-rc1.txt snapshot created
                    │                staged patches reset to candidates
                    │                    ↓
                    │             promote rc → X.Y.Z-rc2.txt (if fixes needed)
                    │
                    └─→ promote prod → X.Y.Z.txt snapshot created
                                       X.Y.Z-patches.toml deleted

Key point: promote prod creates a .txt snapshot from staged patches in the TOML file, then deletes the TOML file. RC files are kept for history only.

File lifecycle (hotfix workflow):

release hotfix → Reopens X.Y.Z-patches.toml
                    ↓
patch merge → X.Y.Z-patches.toml (adds hotfix patches as staged)
                    ↓
promote hotfix → X.Y.Z-hotfixN.txt (snapshot created, TOML deleted)

TOML file format:

[patches]
"patch-id" = "candidate"  # or "staged"

TXT snapshot format (RC/prod/hotfix):

Each line contains a patch ID
Lines starting with # are comments
Empty lines are ignored

Patch Directory Structure

Patches/
└── 123-feature-name/
    ├── README.md           (auto-generated description)
    ├── 01_schema.sql       (schema changes)
    ├── 02_data.sql         (data migrations)
    └── 03_indexes.sql      (performance optimizations)

Execution order: Lexicographic (01, 02, 03...)

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes, minor changes (1.3.5 → 1.3.6)
  │     └──────── New features, backward compatible (1.3.5 → 1.4.0)
  └────────────── Breaking changes (1.3.5 → 2.0.0)

Workflow Rules

Sequential releases: Must promote 0.17.0 before 0.17.1 or 0.18.0
Auto-detection: Commands automatically detect smallest version to promote
Patch origin: Must create patches from ho-release/* branch, not ho-prod
Patch lifecycle: new → candidates → close → stage → rc → prod
Branch cleanup:
- patch merge deletes ho-patch/* branch
- promote prod deletes ho-release/* branch
Database restore: patch apply always restores from production state
Immutable releases: RC and production files never modified
Automatic Git operations: Push/pull handled by commands automatically
⚠️ SYSTEMATIC TEST VALIDATION: Tests run before integration (in patch merge)
Hotfix exception: Can reopen production version while other releases in progress
# HOTFIX marker: Candidates file marked with # HOTFIX comment for hotfix releases

🔧 Troubleshooting

Error: "Must be on ho-release/* branch"

# Solution: Create release or switch to release branch
half_orm dev release new minor
# or
git checkout ho-release/0.17.0

Error: "Must be on ho-patch/* branch"

# Solution: Create or switch to patch branch
# First ensure you're on ho-release/*
git checkout ho-release/0.17.0
half_orm dev patch create <patch_id>
# or
git checkout ho-patch/<patch_id>

Error: "Patch not found in candidates file"

# Solution: Patch must be created from ho-release/* branch
# to be automatically added to candidates
git checkout ho-release/0.17.0
half_orm dev patch create <patch_id>

Error: "Repository is not clean"

# Solution: Commit or stash changes
git status
git add .
git commit -m "Your message"
# or
git stash

Error: "Repository not synced with origin"

# This should not happen - commands handle git operations automatically
# If it does occur:
git pull origin ho-prod

Error: "No stage releases found"

# Solution: Prepare a release first
half_orm dev release new patch

Error: "Active RC exists"

# Cannot promote different version while RC exists
# Solution: Promote current RC to production first
half_orm dev release promote prod

# Then promote your stage
half_orm dev release promote rc

Error: "Tests failed for patch integration"

# Tests ran on temp-valid branch and failed
# Solution: Fix your tests or code
half_orm dev patch apply  # Test locally first
pytest  # Verify tests pass

# Fix issues in your patch
vim Patches/123-feature/01_schema.sql
vim tests/test_feature.py

# Try again
git checkout ho-patch/123-feature
half_orm dev patch merge  # Tests will run again

Patch apply failed (SQL error)

# Database automatically rolled back
# Solution: Fix SQL files and re-apply
vim Patches/123-feature/01_schema.sql
half_orm dev patch apply

Lost after conflicts

# View repository state
git status
git log --oneline -10

# View current branch
git branch

# View remote branches
git branch -r

# Return to safe state
git checkout ho-prod
# Commands handle git pull automatically

🎓 Best Practices

Patch Development

✅ DO:

Write tests FIRST (TDD approach)
Start with exploratory patches (no release needed initially)
Use descriptive patch IDs: 123-add-user-authentication
Test patches thoroughly before adding to release
Keep patches focused (one feature per patch)
Commit generated code with meaningful messages
Create release when patches are ready to integrate
Run pytest locally before patch merge

❌ DON'T:

Mix multiple features in one patch
Skip patch apply validation
Add untested patches to release
Modify files outside your patch directory
Worry about git push/pull (commands handle it automatically)
Skip writing tests (validation will fail anyway)

Release Management

✅ DO:

Prepare releases when patches are ready to integrate
Trust the automatic test validation system
Test RC thoroughly before promoting to production
Use semantic versioning consistently
Document breaking changes in commit messages
Let commands handle git operations automatically
Review test failures carefully before retrying

❌ DON'T:

Skip RC validation (always test before prod)
Promote multiple RCs simultaneously
Skip backup creation in production
Force promote without fixing issues
Manually push/pull (let commands handle it)
Bypass test validation (it's there for your safety)

Production Deployment

✅ DO:

Always run update first to check available releases
Use --dry-run to preview changes
Verify backups exist before upgrade
Monitor application after deployment
Schedule deployments during low-traffic periods
Trust commands to handle git operations
Verify all tests passed in RC before promoting

❌ DON'T:

Deploy without testing in RC first
Skip backup verification
Deploy during peak usage hours
Ignore upgrade warnings
Apply patches directly without releases
Manually git pull (commands do it automatically)
Promote to production if RC tests failed

Testing Best Practices

✅ DO:

Write tests for all business logic
Test database constraints and validations
Use fixtures for common test scenarios
Test edge cases and error handling
Keep tests fast and isolated
Document test intentions clearly
Run tests locally before pushing

❌ DON'T:

Skip tests for "simple" changes
Write tests that depend on execution order
Ignore test failures
Write tests without assertions
Test implementation details instead of behavior

📚 Documentation

Quick Reference: This README

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Development Setup

# Clone repository
git clone https://github.com/half-orm/half-orm-dev.git
cd half-orm-dev

# Install in development mode
pip install -e .

# Run tests
pytest

📞 Getting Help

# Command help
half_orm dev --help
half_orm dev patch --help
half_orm dev release --help

# Specific command help
half_orm dev patch create --help
half_orm dev release promote --help
half_orm dev update --help
half_orm dev upgrade --help

Support

Issues: GitHub Issues
Documentation: docs/
half-orm: half-orm Documentation

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Version: 0.17.0 half-orm: Compatible with half-orm 0.17.x Python: 3.8+ PostgreSQL: Tested with 13+ (might work with earlier versions)

Made with ❤️ by the half-orm team

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

1.0.0a18 pre-release

May 19, 2026

1.0.0a17 pre-release yanked

May 19, 2026

1.0.0a16 pre-release

May 19, 2026

1.0.0a15 pre-release

May 14, 2026

1.0.0a14 pre-release

May 13, 2026

1.0.0a12 pre-release

May 12, 2026

1.0.0a11 pre-release

May 12, 2026

1.0.0a10 pre-release

May 12, 2026

1.0.0a9 pre-release

May 11, 2026

1.0.0a8 pre-release yanked

May 11, 2026

1.0.0a7 pre-release yanked

May 7, 2026

1.0.0a6 pre-release

May 7, 2026

1.0.0a5 pre-release

May 7, 2026

1.0.0a4 pre-release

May 6, 2026

1.0.0a2 pre-release

Apr 17, 2026

0.18.0a2 pre-release

Mar 25, 2026

0.18.0a1 pre-release

Mar 19, 2026

0.17.5a8 pre-release

Feb 27, 2026

0.17.5a7 pre-release

Feb 27, 2026

0.17.5a6 pre-release

Feb 24, 2026

0.17.5a5 pre-release

Feb 16, 2026

0.17.5a4 pre-release

Feb 16, 2026

0.17.5a3 pre-release

Feb 10, 2026

0.17.5a2 pre-release

Feb 9, 2026

0.17.4a3 pre-release

Feb 5, 2026

0.17.4a2 pre-release

Feb 4, 2026

0.17.3a9 pre-release

Jan 30, 2026

0.17.3a8 pre-release

Jan 27, 2026

0.17.3a7 pre-release

Jan 27, 2026

0.17.3a6 pre-release

Jan 26, 2026

0.17.3a5 pre-release

Jan 20, 2026

0.17.3a4 pre-release

Jan 19, 2026

0.17.3a3 pre-release

Jan 14, 2026

This version

0.17.3a2 pre-release

Jan 14, 2026

0.17.3a1 pre-release

Dec 18, 2025

0.17.2a11 pre-release

Dec 18, 2025

0.17.2a10 pre-release

Dec 18, 2025

0.17.2a9 pre-release

Dec 18, 2025

0.17.2a8 pre-release

Dec 18, 2025

0.17.2a7 pre-release

Dec 17, 2025

0.17.2a6 pre-release

Dec 16, 2025

0.17.2a5 pre-release

Dec 15, 2025

0.17.2a4 pre-release

Dec 12, 2025

0.17.2a3 pre-release

Dec 10, 2025

0.17.0a15 pre-release

Dec 4, 2025

0.17.0a14 pre-release

Dec 2, 2025

0.17.0a13 pre-release

Dec 2, 2025

0.17.0a12 pre-release

Dec 2, 2025

0.17.0a11 pre-release

Dec 1, 2025

0.17.0a10 pre-release

Nov 29, 2025

0.17.0a8 pre-release

Nov 28, 2025

0.17.0a7 pre-release

Nov 26, 2025

0.17.0a5 pre-release

Nov 24, 2025

0.17.0a4 pre-release

Nov 24, 2025

0.17.0a3 pre-release

Nov 21, 2025

0.17.0a2 pre-release

Nov 21, 2025

0.17.0a1 pre-release

Nov 17, 2025

0.16.0a10 pre-release

Nov 6, 2025

0.16.0a9 pre-release

Nov 5, 2025

0.16.0a8 pre-release

Nov 4, 2025

0.16.0a7 pre-release

Nov 4, 2025

0.16.0a6 pre-release

Nov 4, 2025

0.16.0a5 pre-release

Sep 24, 2025

0.16.0a4 pre-release

Sep 19, 2025

0.16.0a3 pre-release

Sep 11, 2025

0.16.0a2 pre-release

Sep 10, 2025

0.16.0a1 pre-release

Aug 18, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

half_orm_dev-0.17.3a2.tar.gz (175.2 kB view details)

Uploaded Jan 14, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

half_orm_dev-0.17.3a2-py3-none-any.whl (170.1 kB view details)

Uploaded Jan 14, 2026 Python 3

File details

Details for the file half_orm_dev-0.17.3a2.tar.gz.

File metadata

Download URL: half_orm_dev-0.17.3a2.tar.gz
Upload date: Jan 14, 2026
Size: 175.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.0

File hashes

Hashes for half_orm_dev-0.17.3a2.tar.gz
Algorithm	Hash digest
SHA256	`a7c0f49cff906a1d9438981d104feb67c47a4b0eca4f10f7e8cbfd26f3ce70de`
MD5	`e8880b6919105be1e45bcf1868144f98`
BLAKE2b-256	`dd6468efcbf20cd071945c85dfa5a68664886c4dfd901f47ddbe631c3c172541`

See more details on using hashes here.

File details

Details for the file half_orm_dev-0.17.3a2-py3-none-any.whl.

File metadata

Download URL: half_orm_dev-0.17.3a2-py3-none-any.whl
Upload date: Jan 14, 2026
Size: 170.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.0

File hashes

Hashes for half_orm_dev-0.17.3a2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`a7262abe27cf5310e74a12306024f346f1cff3c34de7fd5d8f9caddfd2d3e758`
MD5	`c331ab5bd2b2c43cb48e4f93e70e93ee`
BLAKE2b-256	`3e36d93a95eaa6427e59022f703b140ec3e483cb56b8e7f053d2e2f1554e261b`

See more details on using hashes here.

half-orm-dev 0.17.3a2

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

half-orm-dev

WARNING! half-orm-dev is in alpha development phase!

📖 Description

✨ Features

🔧 Development

🧪 Test-Driven Development & Validation

📦 Release Management

🚀 Production

👥 Team Collaboration

🚀 Installation

Prerequisites

Install

Verify Installation

📖 Quick Start

Initialize New Project

Clone Existing Project

First Patch (TDD Development)

💻 Development Workflow

Vision: Git-Flow Release Management

Complete Cycle: Patch → Release → Deploy

Workflow Details

Concepts: Release Files and Patch States

Step 1: Create a New Release

Step 2: Create a Candidate Patch

Step 3: Develop and Test (TDD Approach)

Step 4: Close Patch (Integrate to Release)

Step 5: Synchronize with Other Integrated Patches

Step 6: Promote to RC

Step 7: Promote to Production

Step 8/9: Production Upgrade

Hotfix Workflow (Urgent Production Fixes)

📖 Command Reference

Init & Clone

Patch Commands

Release Commands

Production Commands

🎯 Common Patterns

Pattern 1: Planned Development with Integration Branch

Pattern 2: Team Collaboration on Same Release

Pattern 3: Parallel Development of Different Releases

Pattern 4: Incremental RC (Fix Issues)

Pattern 5: Hotfix on Production

Pattern 6: Production Deployment

🏗️ Architecture

Branch Strategy

Release Files

Patch Directory Structure

Semantic Versioning

Workflow Rules

🔧 Troubleshooting

Error: "Must be on ho-release/* branch"

Error: "Must be on ho-patch/* branch"

Error: "Patch not found in candidates file"

Error: "Repository is not clean"

Error: "Repository not synced with origin"

Error: "No stage releases found"

Error: "Active RC exists"

Error: "Tests failed for patch integration"

Patch apply failed (SQL error)

Lost after conflicts

🎓 Best Practices

Patch Development

Release Management

Production Deployment

Testing Best Practices

📚 Documentation

🤝 Contributing

Development Setup

📞 Getting Help

Support

📄 License