Skip to main content

GeoETL v0.1.2: Better Error Handling & Automated Deployments

· 5 min read
Yogesh
Yogesh
GeoETL Maintainer

TL;DR: GeoETL v0.1.2 improves error handling with custom error types and automates documentation deployment to Cloudflare Pages on every release.

Why This Release Matters​

After the successful v0.1.0 launch, we're focusing on two critical areas:

  1. Developer Experience - Clear, actionable error messages
  2. Documentation Accessibility - Automated deployment ensures docs are always up-to-date

This release lays the foundation for robust error handling as we scale to support more formats and operations.

Headline Features​

🎯 Comprehensive Custom Error Types​

Problem: Generic error messages like "Error: IO error" don't help users understand what went wrong or how to fix it. Generic anyhow::Error types made debugging difficult for contributors.

Solution: We implemented a custom GeoEtlError enum with specialized error types for different failure scenarios.

Value: Clear, actionable error messages that tell users exactly what went wrong and often suggest how to fix it.

Error Categories:

pub enum GeoEtlError {
    Io(std::io::Error),              // File I/O errors
    Driver(String),                  // Driver not found or unsupported
    Format(String),                  // Invalid format or parsing errors
    Conversion(String),              // Data conversion failures
    Validation(String),              // Input validation errors
    Configuration(String),           // Configuration issues
    DataProcessing(String),          // Data processing errors
    Geometry(String),                // Geometry-specific errors
}

Before vs After:

# Before v0.1.2
Error: IO error

# After v0.1.2
Error: IO error - Failed to read input file '/path/to/file.geojson'
Caused by: No such file or directory

Suggestion: Check that the file path is correct and the file exists.
# Before v0.1.2
Error: Driver error

# After v0.1.2
Error: Driver 'Shapefile' not found

Available drivers: CSV, GeoJSON
Suggestion: Use --input-driver CSV or --input-driver GeoJSON

Coverage: Error handling integrated across all crates:

  • ✅ geoetl-cli - User-facing error messages
  • ✅ geoetl-core - Core business logic errors
  • ✅ geoetl-operations - Operation-specific errors

Testing: All error handling tests passing, ensuring reliability.

🚀 Automated Documentation Deployment​

Problem: Documentation changes required manual deployment steps, leading to outdated docs on the website after releases.

Solution: Integrated Cloudflare Pages deployment into the release workflow using CircleCI and Wrangler CLI.

Value: Always up-to-date documentation. Every GitHub release automatically triggers a production deployment.

Workflow:

  1. Developer creates a Git tag (e.g., v0.1.2)
  2. CircleCI detects the tag and runs tests
  3. Documentation site builds automatically
  4. Wrangler CLI deploys to Cloudflare Pages
  5. Documentation goes live at https://geoetl-web-circleci.pages.dev

Benefits:

  • 📚 Documentation always matches the latest release
  • ⏱️ Zero manual deployment steps
  • 🔄 Consistent deployment process
  • 🌍 Fast global CDN delivery via Cloudflare

Other Improvements & Fixes​

Changed​

Documentation Reorganization:

We cleaned up documentation to eliminate redundancy and improve discoverability:

  • ✅ Removed docs/USERGUIDE.md - Content already available on the documentation website (https://geoetl.com)
  • ✅ Updated references - All links in README.md, QUICKREF.md, DEVELOPMENT.md now point to the website
  • ✅ Moved format docs - Format-specific documentation moved to package directories:
    • docs/formats/csv-*.md → crates/formats/datafusion-csv/docs/
    • docs/formats/geojson-*.md → crates/formats/datafusion-geojson/docs/
  • ✅ Updated integration guide - DataFusion integration guide reflects new documentation paths

Philosophy: Single source of truth. Documentation lives close to the code it describes.

Removed​

  • 🗑️ docs/USERGUIDE.md - Superseded by documentation website
  • 🗑️ docs/formats/ directory - Moved to respective package directories

⚠️ Breaking Changes​

None - this release is fully backward compatible with v0.1.0 and v0.1.1.

Community & Contributors​

Thank you to everyone who:

  • Reported unclear error messages
  • Requested better documentation
  • Contributed to the GeoRust ecosystem

Special acknowledgment to:

  • Apache DataFusion team for excellent error handling patterns
  • CircleCI for robust CI/CD infrastructure
  • Cloudflare for fast, reliable Pages hosting

The Future: What's Next?​

v0.1.2 sets us up for the major performance improvements coming in v0.2.0:

v0.2.0 (Coming Soon):

  • 🎯 Streaming architecture - Process files larger than RAM
  • 🎯 Performance benchmarks - Real-world performance testing
  • 🎯 Configurable batch sizes - Tune memory/speed tradeoff
  • 🎯 Comprehensive ADRs - Architecture decision records

Later releases:

  • 🚀 GeoParquet support (v0.3.0)
  • 🚀 More format drivers (v0.4.0+)
  • 🚀 Spatial operations (v0.5.0+)

See our full Roadmap for details.

How to Upgrade​

Installation​

From source:

git clone https://github.com/geoyogesh/geoetl.git
cd geoetl
git checkout v0.1.2
cargo build --release

# Binary at: target/release/geoetl-cli

Verify Installation​

$ geoetl-cli --version
geoetl-cli 0.1.2

Get Started Today​

Test the improved error messages:

# Try converting with a non-existent file
$ geoetl-cli convert \
  --input missing.geojson \
  --output output.csv \
  --input-driver GeoJSON \
  --output-driver CSV

# You'll get a helpful error message with suggestions!

# Try using an unavailable driver
$ geoetl-cli convert \
  --input data.geojson \
  --output data.shp \
  --input-driver GeoJSON \
  --output-driver Shapefile

# Error will show available drivers and suggestions

Documentation​

Get Involved​

We'd love your help making GeoETL better:

Download: GeoETL v0.1.2

Have questions or feedback? Join the discussion on GitHub!