half-orm-dev 0.17.4a2__tar.gz → 0.17.5a1__tar.gz

{half_orm_dev-0.17.4a2/half_orm_dev.egg-info → half_orm_dev-0.17.5a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: half_orm_dev
-Version: 0.17.4a2
+Version: 0.17.5a1
 Summary: half_orm development Framework.
 Author-email: Joël Maïzi <joel.maizi@collorg.org>
 License-Expression: GPL-3.0-or-later
@@ -35,7 +35,7 @@ Dynamic: requires-dist
 
 > **Please report any issues at [GitHub Issues](https://github.com/half-orm/half-orm-dev/issues)**
 
-**Git-centric patch management and database versioning for half-orm projects**
+**Git-centric patch management and PostgreSQL database versioning for half-orm projects**
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
@@ -53,6 +53,7 @@ Modern development workflow for PostgreSQL databases with automatic code generat
 - **Git-centric workflow**: Patches stored in Git branches with semantic versioning
 - **Test-Driven Development**: **Automatic validation** - tests run before integration, patches blocked if tests fail
 - **Code generation**: Python classes auto-generated from schema changes
+- **Data bootstrapping**: Initialize reference data and configurations with tracked scripts
 - **Safe deployments**: Sequential releases with automatic backups and validation
 - **Team collaboration**: Distributed locks, branch management, conflict prevention
 - **Cloud-friendly**: No superuser privileges required (works on AWS RDS, Azure, GCP)
@@ -74,10 +75,11 @@ half_orm dev patch merge
 
 # Behind the scenes:
 # 1. Creates temporary validation branch
-# 2. Merges ALL patches in release context
-# 3. Runs pytest automatically
-# 4. ✅ If PASS → merges into release, status → "staged"
-# 5. ❌ If FAIL → nothing committed, temp branch deleted
+# 2. Restores database from production schema
+# 3. Applies ALL release patches sequentially
+# 4. Runs pytest automatically
+# 5. ✅ If PASS → merges into release, status → "staged"
+# 6. ❌ If FAIL → nothing committed, temp branch deleted
 ```
 
 **Benefits:**
@@ -100,6 +102,7 @@ half_orm dev patch merge
 - **Semantic versioning**: patch/minor/major increments
 - **Sequential promotion**: stage → rc → production workflow
 - **Release candidates**: RC validation before production
+- **Hotfix support**: Reopen last released version for urgent fixes
 - **Branch cleanup**: Automatic deletion after promotion
 
 ### 🚀 Production
@@ -115,8 +118,8 @@ half_orm dev patch merge
 
 ### Prerequisites
 
-- **Python 3.9+** required
-- **PostgreSQL 12+** recommended
+- **Python**: [Active versions](https://devguide.python.org/versions/) (currently 3.9+)
+- **PostgreSQL**: [Supported versions](https://www.postgresql.org/support/versioning/) (currently 13+)
 - **Git** for version control
 
 ### Install
@@ -138,8 +141,8 @@ half_orm dev --help
 ### Initialize New Project
 
 ```bash
-# Create project with database
-half_orm dev init myproject --database mydb
+# Create project with database (requires git origin)
+half_orm dev init myproject --database mydb --git-origin git@github.com:user/myproject.git
 cd myproject
 ```
 
@@ -235,6 +238,7 @@ ho-prod (main production branch)
 ├── 0.17.0-patches.toml    # Development (mutable: candidate/staged status)
 ├── 0.17.0-rc1.txt         # Release candidate snapshot (immutable)
 ├── 0.17.0.txt             # Production snapshot (immutable)
+├── 0.17.0-hotfix1.txt     # Hotfix snapshot (immutable)
 └── 0.18.0-patches.toml    # Next version in progress
 ```
 
@@ -249,7 +253,7 @@ ho-prod (main production branch)
 ┌─────────────────────────────────────────────────────────────┐
 │ DEVELOPMENT WORKFLOW                                        │
 ├─────────────────────────────────────────────────────────────┤
-│ 1. release create <level>     Create ho-release/X.Y.Z          │
+│ 1. release create <level>     Create ho-release/X.Y.Z       │
 │ 2. patch create <id>       Create patch (auto-candidate)    │
 │ 3. patch apply             Apply & test changes             │
 │ 4. patch merge             Merge into release (TESTS!)      │
@@ -263,6 +267,11 @@ ho-prod (main production branch)
 │ PRODUCTION DEPLOYMENT                                       │
 │ 7. update                  Check available releases         │
 │ 8. upgrade                 Apply on production servers      │
+│                                                             │
+│ HOTFIX (urgent production fix)                              │
+│ 9. release hotfix          Reopen last released version     │
+│10. patch create/merge      Fix and validate                 │
+│11. release promote hotfix  Deploy hotfix                    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -273,33 +282,31 @@ ho-prod (main production branch)
 ### Init & Clone
 
 ```bash
-# Create new project
-half_orm dev init <package_name> --database <db_name>
+# Create new project (requires git origin)
+half_orm dev init <package_name> --database <db_name> --git-origin <url>
 
 # Clone existing project
 half_orm dev clone <git_origin>
 ```
 
-### Patch Commands
+### Check
 
 ```bash
-# Create new patch (must be on ho-release/* branch)
-half_orm dev patch create <patch_id>
-
-# Apply current patch (must be on ho-patch/* branch)
-half_orm dev patch apply
+# Verify and update project configuration
+half_orm dev check
 
-# Merge patch into release (AUTOMATIC VALIDATION!)
-# Must be on ho-patch/* branch
-half_orm dev patch merge
+# Preview what would be done
+half_orm dev check --dry-run
 ```
 
-**Tip:** Patch IDs must start with a number (e.g., `123-add-users`). This number automatically closes the corresponding GitHub/GitLab issue #123 when the patch is merged.
+**Note:** This command runs automatically before other commands (git hooks, configuration, stale branches cleanup).
 
 ### Release Commands
 
+A release must be created before creating patches.
+
 ```bash
-# Create new release
+# Create new release (must be on ho-prod branch)
 half_orm dev release create patch   # X.Y.(Z+1)
 half_orm dev release create minor   # X.(Y+1).0
 half_orm dev release create major   # (X+1).0.0
@@ -315,6 +322,24 @@ half_orm dev release hotfix           # Reopen production version
 half_orm dev release promote hotfix   # Deploy hotfix
 ```
 
+### Patch Commands
+
+```bash
+# Create new patch (must be on ho-release/* branch)
+half_orm dev patch create <patch_id>
+
+# Apply current patch (must be on ho-patch/* branch)
+half_orm dev patch apply
+
+# Merge patch into release (AUTOMATIC VALIDATION!)
+# Must be on ho-patch/* branch
+half_orm dev patch merge
+```
+
+**Tip:** Patch IDs must start with a number (e.g., `123-add-users`). This number automatically closes the corresponding GitHub/GitLab issue #123 when the patch is merged.
+
+**Patch files:** SQL (`.sql`) or Python (`.py`) files in `Patches/<patch_id>/`, executed in lexicographic order.
+
 ### Production Commands
 
 ```bash
@@ -328,6 +353,20 @@ half_orm dev upgrade [--to-release X.Y.Z]
 half_orm dev upgrade --dry-run
 ```
 
+### Data Bootstrap
+
+Mark patch files with `-- @HOP:bootstrap` (SQL) or `# @HOP:bootstrap` (Python) to declare reference data:
+
+```sql
+-- @HOP:bootstrap
+INSERT INTO roles (name) VALUES ('admin'), ('user') ON CONFLICT DO NOTHING;
+```
+
+These files are automatically:
+- Copied to `bootstrap/` during `patch merge`
+- Executed during production `upgrade`
+- Tracked in database (each script runs once)
+
 **Note:** Use `half_orm dev <command> --help` for detailed help on each command.
 
 ---
@@ -360,47 +399,17 @@ half_orm dev patch merge
 
 ---
 
-## 🎓 Best Practices
-
-### Development
-✅ **DO:**
-- Write tests FIRST (TDD approach)
-- Run `pytest` locally before `patch merge`
-- Use descriptive patch IDs: `123-add-user-authentication`
-- Keep patches focused (one feature per patch)
-- Test patches thoroughly
-
-❌ **DON'T:**
-- Skip writing tests (validation will fail anyway)
-- Mix multiple features in one patch
-- Bypass test validation (it's there for safety)
-- Modify files outside your patch directory
-
-### Release Management
-✅ **DO:**
-- Trust the automatic test validation system
-- Test RC thoroughly before promoting to production
-- Use semantic versioning consistently
-- Review test failures carefully before retrying
-
-❌ **DON'T:**
-- Skip RC validation
-- Force promote without fixing issues
-- Bypass test validation
-- Ignore test failures
-
-### Production Deployment
-✅ **DO:**
-- Always run `update` first to check available releases
-- Use `--dry-run` to preview changes
-- Verify backups exist before upgrade
-- Verify all tests passed in RC before promoting
-
-❌ **DON'T:**
-- Deploy without testing in RC first
-- Skip backup verification
-- Promote to production if RC tests failed
-- Apply patches directly without releases
+## 🎓 Development Philosophy
+
+half-orm-dev combines **Domain-Driven Design** with **Test-Driven Development**, integrated into Git:
+
+1. **Schema as domain model** - The PostgreSQL schema defines your domain; Python classes are auto-generated
+2. **Write tests first** - Define expected behavior before implementation
+3. **Develop in isolation** - Each patch has its own branch and directory
+4. **Validate automatically** - Tests run during `patch merge`, blocking integration if they fail
+5. **Deploy with confidence** - Only validated code reaches production
+
+This approach ensures that every schema change is tested in the full release context before integration.
 
 ---
 
@@ -463,11 +472,11 @@ git stash
 git pull origin ho-prod
 ```
 
-### Error: "No stage releases found"
+### Error: "No staged releases found"
 
 ```bash
-# Solution: Prepare a release first
-half_orm dev release new patch
+# Solution: Create a release first
+half_orm dev release create patch
 ```
 
 ### Error: "Active RC exists"
@@ -496,16 +505,6 @@ git checkout ho-patch/123-feature
 half_orm dev patch merge  # Tests will run again
 ```
 
-### Error: "Repository is not clean"
-```bash
-# Commit or stash changes
-git status
-git add .
-git commit -m "Your message"
-# or
-git stash
-```
-
 For more troubleshooting, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ---

{half_orm_dev-0.17.4a2 → half_orm_dev-0.17.5a1}/README.md

@@ -4,7 +4,7 @@
 
 > **Please report any issues at [GitHub Issues](https://github.com/half-orm/half-orm-dev/issues)**
 
-**Git-centric patch management and database versioning for half-orm projects**
+**Git-centric patch management and PostgreSQL database versioning for half-orm projects**
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
@@ -22,6 +22,7 @@ Modern development workflow for PostgreSQL databases with automatic code generat
 - **Git-centric workflow**: Patches stored in Git branches with semantic versioning
 - **Test-Driven Development**: **Automatic validation** - tests run before integration, patches blocked if tests fail
 - **Code generation**: Python classes auto-generated from schema changes
+- **Data bootstrapping**: Initialize reference data and configurations with tracked scripts
 - **Safe deployments**: Sequential releases with automatic backups and validation
 - **Team collaboration**: Distributed locks, branch management, conflict prevention
 - **Cloud-friendly**: No superuser privileges required (works on AWS RDS, Azure, GCP)
@@ -43,10 +44,11 @@ half_orm dev patch merge
 
 # Behind the scenes:
 # 1. Creates temporary validation branch
-# 2. Merges ALL patches in release context
-# 3. Runs pytest automatically
-# 4. ✅ If PASS → merges into release, status → "staged"
-# 5. ❌ If FAIL → nothing committed, temp branch deleted
+# 2. Restores database from production schema
+# 3. Applies ALL release patches sequentially
+# 4. Runs pytest automatically
+# 5. ✅ If PASS → merges into release, status → "staged"
+# 6. ❌ If FAIL → nothing committed, temp branch deleted
 ```
 
 **Benefits:**
@@ -69,6 +71,7 @@ half_orm dev patch merge
 - **Semantic versioning**: patch/minor/major increments
 - **Sequential promotion**: stage → rc → production workflow
 - **Release candidates**: RC validation before production
+- **Hotfix support**: Reopen last released version for urgent fixes
 - **Branch cleanup**: Automatic deletion after promotion
 
 ### 🚀 Production
@@ -84,8 +87,8 @@ half_orm dev patch merge
 
 ### Prerequisites
 
-- **Python 3.9+** required
-- **PostgreSQL 12+** recommended
+- **Python**: [Active versions](https://devguide.python.org/versions/) (currently 3.9+)
+- **PostgreSQL**: [Supported versions](https://www.postgresql.org/support/versioning/) (currently 13+)
 - **Git** for version control
 
 ### Install
@@ -107,8 +110,8 @@ half_orm dev --help
 ### Initialize New Project
 
 ```bash
-# Create project with database
-half_orm dev init myproject --database mydb
+# Create project with database (requires git origin)
+half_orm dev init myproject --database mydb --git-origin git@github.com:user/myproject.git
 cd myproject
 ```
 
@@ -204,6 +207,7 @@ ho-prod (main production branch)
 ├── 0.17.0-patches.toml    # Development (mutable: candidate/staged status)
 ├── 0.17.0-rc1.txt         # Release candidate snapshot (immutable)
 ├── 0.17.0.txt             # Production snapshot (immutable)
+├── 0.17.0-hotfix1.txt     # Hotfix snapshot (immutable)
 └── 0.18.0-patches.toml    # Next version in progress
 ```
 
@@ -218,7 +222,7 @@ ho-prod (main production branch)
 ┌─────────────────────────────────────────────────────────────┐
 │ DEVELOPMENT WORKFLOW                                        │
 ├─────────────────────────────────────────────────────────────┤
-│ 1. release create <level>     Create ho-release/X.Y.Z          │
+│ 1. release create <level>     Create ho-release/X.Y.Z       │
 │ 2. patch create <id>       Create patch (auto-candidate)    │
 │ 3. patch apply             Apply & test changes             │
 │ 4. patch merge             Merge into release (TESTS!)      │
@@ -232,6 +236,11 @@ ho-prod (main production branch)
 │ PRODUCTION DEPLOYMENT                                       │
 │ 7. update                  Check available releases         │
 │ 8. upgrade                 Apply on production servers      │
+│                                                             │
+│ HOTFIX (urgent production fix)                              │
+│ 9. release hotfix          Reopen last released version     │
+│10. patch create/merge      Fix and validate                 │
+│11. release promote hotfix  Deploy hotfix                    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -242,33 +251,31 @@ ho-prod (main production branch)
 ### Init & Clone
 
 ```bash
-# Create new project
-half_orm dev init <package_name> --database <db_name>
+# Create new project (requires git origin)
+half_orm dev init <package_name> --database <db_name> --git-origin <url>
 
 # Clone existing project
 half_orm dev clone <git_origin>
 ```
 
-### Patch Commands
+### Check
 
 ```bash
-# Create new patch (must be on ho-release/* branch)
-half_orm dev patch create <patch_id>
-
-# Apply current patch (must be on ho-patch/* branch)
-half_orm dev patch apply
+# Verify and update project configuration
+half_orm dev check
 
-# Merge patch into release (AUTOMATIC VALIDATION!)
-# Must be on ho-patch/* branch
-half_orm dev patch merge
+# Preview what would be done
+half_orm dev check --dry-run
 ```
 
-**Tip:** Patch IDs must start with a number (e.g., `123-add-users`). This number automatically closes the corresponding GitHub/GitLab issue #123 when the patch is merged.
+**Note:** This command runs automatically before other commands (git hooks, configuration, stale branches cleanup).
 
 ### Release Commands
 
+A release must be created before creating patches.
+
 ```bash
-# Create new release
+# Create new release (must be on ho-prod branch)
 half_orm dev release create patch   # X.Y.(Z+1)
 half_orm dev release create minor   # X.(Y+1).0
 half_orm dev release create major   # (X+1).0.0
@@ -284,6 +291,24 @@ half_orm dev release hotfix           # Reopen production version
 half_orm dev release promote hotfix   # Deploy hotfix
 ```
 
+### Patch Commands
+
+```bash
+# Create new patch (must be on ho-release/* branch)
+half_orm dev patch create <patch_id>
+
+# Apply current patch (must be on ho-patch/* branch)
+half_orm dev patch apply
+
+# Merge patch into release (AUTOMATIC VALIDATION!)
+# Must be on ho-patch/* branch
+half_orm dev patch merge
+```
+
+**Tip:** Patch IDs must start with a number (e.g., `123-add-users`). This number automatically closes the corresponding GitHub/GitLab issue #123 when the patch is merged.
+
+**Patch files:** SQL (`.sql`) or Python (`.py`) files in `Patches/<patch_id>/`, executed in lexicographic order.
+
 ### Production Commands
 
 ```bash
@@ -297,6 +322,20 @@ half_orm dev upgrade [--to-release X.Y.Z]
 half_orm dev upgrade --dry-run
 ```
 
+### Data Bootstrap
+
+Mark patch files with `-- @HOP:bootstrap` (SQL) or `# @HOP:bootstrap` (Python) to declare reference data:
+
+```sql
+-- @HOP:bootstrap
+INSERT INTO roles (name) VALUES ('admin'), ('user') ON CONFLICT DO NOTHING;
+```
+
+These files are automatically:
+- Copied to `bootstrap/` during `patch merge`
+- Executed during production `upgrade`
+- Tracked in database (each script runs once)
+
 **Note:** Use `half_orm dev <command> --help` for detailed help on each command.
 
 ---
@@ -329,47 +368,17 @@ half_orm dev patch merge
 
 ---
 
-## 🎓 Best Practices
-
-### Development
-✅ **DO:**
-- Write tests FIRST (TDD approach)
-- Run `pytest` locally before `patch merge`
-- Use descriptive patch IDs: `123-add-user-authentication`
-- Keep patches focused (one feature per patch)
-- Test patches thoroughly
-
-❌ **DON'T:**
-- Skip writing tests (validation will fail anyway)
-- Mix multiple features in one patch
-- Bypass test validation (it's there for safety)
-- Modify files outside your patch directory
-
-### Release Management
-✅ **DO:**
-- Trust the automatic test validation system
-- Test RC thoroughly before promoting to production
-- Use semantic versioning consistently
-- Review test failures carefully before retrying
-
-❌ **DON'T:**
-- Skip RC validation
-- Force promote without fixing issues
-- Bypass test validation
-- Ignore test failures
-
-### Production Deployment
-✅ **DO:**
-- Always run `update` first to check available releases
-- Use `--dry-run` to preview changes
-- Verify backups exist before upgrade
-- Verify all tests passed in RC before promoting
-
-❌ **DON'T:**
-- Deploy without testing in RC first
-- Skip backup verification
-- Promote to production if RC tests failed
-- Apply patches directly without releases
+## 🎓 Development Philosophy
+
+half-orm-dev combines **Domain-Driven Design** with **Test-Driven Development**, integrated into Git:
+
+1. **Schema as domain model** - The PostgreSQL schema defines your domain; Python classes are auto-generated
+2. **Write tests first** - Define expected behavior before implementation
+3. **Develop in isolation** - Each patch has its own branch and directory
+4. **Validate automatically** - Tests run during `patch merge`, blocking integration if they fail
+5. **Deploy with confidence** - Only validated code reaches production
+
+This approach ensures that every schema change is tested in the full release context before integration.
 
 ---
 
@@ -432,11 +441,11 @@ git stash
 git pull origin ho-prod
 ```
 
-### Error: "No stage releases found"
+### Error: "No staged releases found"
 
 ```bash
-# Solution: Prepare a release first
-half_orm dev release new patch
+# Solution: Create a release first
+half_orm dev release create patch
 ```
 
 ### Error: "Active RC exists"
@@ -465,16 +474,6 @@ git checkout ho-patch/123-feature
 half_orm dev patch merge  # Tests will run again
 ```
 
-### Error: "Repository is not clean"
-```bash
-# Commit or stash changes
-git status
-git add .
-git commit -m "Your message"
-# or
-git stash
-```
-
 For more troubleshooting, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ---

{half_orm_dev-0.17.4a2 → half_orm_dev-0.17.5a1}/half_orm_dev/hgit.py

@@ -925,7 +925,7 @@ class HGit:
             match = re.search(r'-(\d+)$', existing_locks[0])
             if match:
                 lock_timestamp_ms = int(match.group(1))
-                lock_time = datetime.utcfromtimestamp(lock_timestamp_ms / 1000.0)
+                lock_time = datetime.fromtimestamp(lock_timestamp_ms / 1000.0, tz=timezone.utc)
                 current_time = datetime.now(timezone.utc)
 
                 # Check if lock is stale

{half_orm_dev-0.17.4a2 → half_orm_dev-0.17.5a1}/half_orm_dev/migration_manager.py

@@ -302,6 +302,9 @@ class MigrationManager:
             self._repo._Repo__config.hop_version = target_version
             self._repo._Repo__config.write()
 
+        # Update half_orm_dev version in pyproject.toml
+        self._update_pyproject_dependency_version(target_version)
+
         # Create Git commit if requested
         if create_commit and self._repo.hgit:
             try:
@@ -367,6 +370,49 @@ class MigrationManager:
 
         return '\n'.join(lines)
 
+    def _update_pyproject_dependency_version(self, target_version: str) -> None:
+        """
+        Update half_orm_dev version in pyproject.toml.
+
+        This ensures the project's dependency on half_orm_dev always matches
+        the current tool version after each migration.
+
+        Handles both == and >= version specifiers.
+
+        Args:
+            target_version: New version to set for half_orm_dev dependency
+        """
+        import re
+
+        pyproject_path = Path(self._repo.base_dir) / "pyproject.toml"
+
+        if not pyproject_path.exists():
+            return
+
+        try:
+            content = pyproject_path.read_text()
+
+            # Only update if half_orm_dev dependency exists (== or >=)
+            if 'half_orm_dev==' not in content and 'half_orm_dev>=' not in content:
+                return
+
+            # Update the version (handles both == and >=)
+            new_content = re.sub(
+                r'half_orm_dev[>=]=[\d.a-zA-Z-]+',
+                f'half_orm_dev=={target_version}',
+                content
+            )
+
+            if new_content != content:
+                pyproject_path.write_text(new_content)
+                if self._repo.hgit:
+                    self._repo.hgit.add(str(pyproject_path))
+                print(f"  Updated pyproject.toml: half_orm_dev=={target_version}")
+
+        except Exception as e:
+            # Non-critical - don't fail migration
+            print(f"  Warning: Could not update pyproject.toml: {e}")
+
     def check_migration_needed(self, current_tool_version: str) -> bool:
         """
         Check if migration is needed.