Document release process and update project status

brendon9x · brendon9x · commit 54b36d887587 · 2025-11-04T12:19:16.000+02:00
- Created RELEASE_PROCESS.md with complete release workflow
- Updated FINE_PLAN.md to reflect Phase 6D completion (prebuilt binaries)
- Updated FINE_PLAN.md status to v0.2.0 released
- Deleted research/GITHUB_RELEASE_PLAN.md (implementation complete)
diff --git a/FINE_PLAN.md b/FINE_PLAN.md
@@ -1,8 +1,8 @@
 # Natch: FINE Wrapper Implementation Plan
 
-**Last Updated:** 2025-11-01
-**Status:** ✅ Phases 1-5 Complete + Phase 6 Timeout Support
-**Timeline:** MVP achieved in ~1 hour, Production-ready with advanced types, nesting, and timeout configuration in ~10 hours
+**Last Updated:** 2025-11-04
+**Status:** ✅ Phases 1-6 Complete + v0.2.0 Released to Hex.pm
+**Timeline:** MVP achieved in ~1 hour, Production-ready v0.2.0 with precompiled binaries published
 
 ---
 
@@ -967,11 +967,49 @@ Added three configurable socket-level timeout options to prevent operations from
 - Multiple Elixir/OTP version combinations verified
 - Zero memory leaks verified via valgrind
 
-**Remaining for Public Release:**
+### ✅ Phase 6D: Prebuilt Binary System (COMPLETED)
+
+**Status:** Complete - v0.2.0 published to Hex.pm with precompiled binaries
+
+**Deliverables Completed:**
+
+1. **Precompiler Configuration**
+   - ✅ mix.exs configured with cc_precompiler
+   - ✅ GitHub release URL template configured
+   - ✅ NIF version 2.17 (OTP 26-28) specified
+   - ✅ checksum*.exs added to package files
+   - ✅ checksum*.exs added to .gitignore
+
+2. **GitHub Actions Workflow**
+   - ✅ Created .github/workflows/precompile.yml
+   - ✅ Builds on tag push (v*)
+   - ✅ 7 platform binaries generated:
+     - x86_64-linux-gnu
+     - aarch64-linux-gnu
+     - x86_64-apple-darwin
+     - aarch64-apple-darwin
+     - armv7l-linux-gnueabihf (cross-compiled)
+     - i686-linux-gnu (cross-compiled)
+     - riscv64-linux-gnu (cross-compiled)
+
+3. **Release Process**
+   - ✅ v0.2.0 tagged and pushed
+   - ✅ GitHub Actions built all binaries
+   - ✅ Checksums generated with `mix elixir_make.checksum --all`
+   - ✅ Published to Hex.pm successfully
+   - ✅ Verified with fresh test installation
+
+**Verification:**
+Created test project that successfully:
+- Downloaded precompiled binary from Hex.pm cache
+- Connected to ClickHouse
+- Executed all basic operations (CREATE, INSERT, SELECT)
+- Tested both row-major and columnar formats
+- Verified type system and aggregations work
+
+**Remaining for Future Releases:**
 - ⏳ Phase 6C: Parameterized queries
-- ⏳ Phase 6D: Prebuilt binaries - 4 tested platforms + cross-compilation (see research/GITHUB_RELEASE_PLAN.md)
-- ⏳ Phase 6E: Documentation polish for public consumption
-- ⏳ Hex.pm publication
+- ⏳ Phase 6E: Additional documentation polish
 
 ### Phase 6C: Parameterized Queries
 
diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md
@@ -0,0 +1,198 @@
+# Natch Release Process
+
+This document describes the complete process for releasing a new version of Natch to Hex.pm with precompiled binaries.
+
+## Prerequisites
+
+- All tests passing locally (`mix test`)
+- All tests passing on GitHub Actions
+- CHANGELOG.md updated with new version
+- No compiler warnings
+
+## Release Steps
+
+### 1. Update Version
+
+Update the version in `mix.exs`:
+
+```elixir
+@version "0.X.Y"
+```
+
+### 2. Update CHANGELOG.md
+
+Add a new section for the release:
+
+```markdown
+## [0.X.Y] - YYYY-MM-DD
+
+### Added
+- New features...
+
+### Changed
+- Changes to existing functionality...
+
+### Fixed
+- Bug fixes...
+```
+
+### 3. Commit and Tag
+
+```bash
+# Commit version bump
+git add mix.exs CHANGELOG.md
+git commit -m "Release v0.X.Y"
+
+# Create annotated tag
+git tag -a v0.X.Y -m "Release v0.X.Y"
+
+# Push to GitHub (triggers precompile workflow)
+git push origin main --tags
+```
+
+### 4. Wait for GitHub Actions
+
+The `.github/workflows/precompile.yml` workflow will automatically:
+- Build precompiled binaries for 7 platforms
+- Upload them to the GitHub Release
+- This takes approximately 10-15 minutes
+
+Monitor the workflow at:
+```
+https://github.com/Intellection/natch/actions
+```
+
+Expected binaries:
+- `natch-nif-2.17-x86_64-linux-gnu-0.X.Y.tar.gz`
+- `natch-nif-2.17-aarch64-linux-gnu-0.X.Y.tar.gz`
+- `natch-nif-2.17-x86_64-apple-darwin-0.X.Y.tar.gz`
+- `natch-nif-2.17-aarch64-apple-darwin-0.X.Y.tar.gz`
+- `natch-nif-2.17-armv7l-linux-gnueabihf-0.X.Y.tar.gz` (cross-compiled)
+- `natch-nif-2.17-i686-linux-gnu-0.X.Y.tar.gz` (cross-compiled)
+- `natch-nif-2.17-riscv64-linux-gnu-0.X.Y.tar.gz` (cross-compiled)
+
+### 5. Generate Checksums
+
+Once GitHub Actions completes:
+
+```bash
+# Generate checksums for all precompiled binaries
+MIX_ENV=prod mix elixir_make.checksum --all --ignore-unavailable
+```
+
+This creates `checksum.exs` in your working directory with SHA256 hashes of all binaries.
+
+**Important:**
+- This file is in `.gitignore` (don't commit it)
+- This file is in `mix.exs` package `files:` list (will be included in Hex package)
+
+### 6. Verify Package
+
+```bash
+# Build the package
+mix hex.build
+
+# Verify checksum.exs is included
+tar -tzf natch-0.X.Y.tar | grep checksum
+
+# Should see: checksum.exs
+```
+
+### 7. Publish to Hex.pm
+
+```bash
+# Publish (will include checksum.exs)
+mix hex.publish
+```
+
+Follow the prompts and confirm the publication.
+
+### 8. Verify Installation
+
+Create a test project to verify:
+
+```bash
+mkdir /tmp/natch-verify && cd /tmp/natch-verify
+mix new . --app test_natch
+```
+
+Add to `mix.exs`:
+```elixir
+{:natch, "~> 0.X.Y"}
+```
+
+Test installation:
+```bash
+mix deps.get
+
+# Look for: "Downloading precompiled NIF to ..."
+# Should NOT see CMake/compiler output
+```
+
+Test functionality:
+```bash
+# With ClickHouse running on localhost:9000
+iex -S mix
+
+iex> {:ok, conn} = Natch.Connection.start_link(host: "localhost", port: 9000)
+iex> Natch.Connection.execute(conn, "SELECT 1")
+```
+
+## Troubleshooting
+
+### Checksums don't match
+- Ensure GitHub Actions completed successfully
+- Check the v0.X.Y release has all 7 binaries
+- Try deleting local cache: `rm -rf ~/.cache/elixir_make/`
+- Re-run: `MIX_ENV=prod mix elixir_make.checksum --all`
+
+### Precompiled binary not downloading
+- Verify checksum.exs is in the Hex package: `mix hex.build` and inspect
+- Check GitHub release has public access to binaries
+- Verify the URL template in mix.exs matches: `https://github.com/Intellection/natch/releases/download/v#{@version}/@{artefact_filename}`
+
+### Build fails for a platform
+- Cross-compiled platforms (armv7l, i686, riscv64) are best-effort
+- Users on those platforms will fall back to source compilation
+- This is expected and acceptable
+
+## Post-Release
+
+1. Announce on:
+   - Elixir Forum
+   - GitHub Discussions
+   - Social media (optional)
+
+2. Monitor for issues:
+   - https://github.com/Intellection/natch/issues
+   - Hex.pm package page
+
+3. Clean up local artifacts:
+   ```bash
+   rm checksum.exs
+   ```
+
+## Quick Reference
+
+```bash
+# Full release in one go (after version updates committed)
+git tag -a v0.X.Y -m "Release v0.X.Y"
+git push origin main --tags
+
+# Wait ~10-15 min for GitHub Actions...
+
+MIX_ENV=prod mix elixir_make.checksum --all --ignore-unavailable
+mix hex.build  # verify
+mix hex.publish
+
+# Clean up
+rm checksum.exs
+```
+
+## Version Strategy
+
+- **Patch (0.X.Y)**: Bug fixes, documentation, minor improvements
+- **Minor (0.X.0)**: New features, new types, API additions (backward compatible)
+- **Major (X.0.0)**: Breaking changes, API redesign
+
+Current: v0.2.0 - First public release with precompiled binaries
diff --git a/research/GITHUB_RELEASE_PLAN.md b/research/GITHUB_RELEASE_PLAN.md
