### Old setup script

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

Example of the old setup process.

```bash
git clone https://github.com/aspectumapp/osm2geojson.git
cd osm2geojson
python setup.py develop
./lint.sh          # Check code
python -m unittest  # Run tests
./release.sh       # Release (manual)
```

--------------------------------

### Development Setup - Manual Installation

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Manual installation steps if the 'make setup' command is not sufficient.

```bash
pip install -e ".[dev]"
pre-commit install

```

--------------------------------

### Test the Build

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Commands to test the package build and installation.

```bash
make test-build

# Or manually:
python -m build
pip install dist/osm2geojson-*.whl
```

--------------------------------

### Prerequisites: One-Time PyPI Setup (Trusted Publishers)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Configuration steps for setting up Trusted Publishers on PyPI.

```text
PyPI Project Name: osm2geojson
Owner: aspectumapp
Repository: osm2geojson
Workflow name: pythonpublish.yml
Environment name: (leave blank)
```

--------------------------------

### Development Setup - Installation

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Commands to clone the repository and set up the development environment.

```bash
# Clone with submodules
git clone --recurse-submodules https://github.com/aspectumapp/osm2geojson.git
cd osm2geojson

# Complete setup (one command)
make setup

```

--------------------------------

### Type Hints Example

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Examples demonstrating the use of type hints in Python code, including Optional and complex types.

```python
# DO add type hints to new functions
def process_element(el: dict, refs_index: dict, raise_on_failure: bool = False) -> Optional[dict]:
    ...

# Use Optional for nullable types
def get_ref(ref_el: dict, refs_index: dict, silent: bool = False) -> Optional[dict]:
    ...

# Complex types
from typing import List, Dict, Optional, Any
def parse_members(members: List[dict]) -> Dict[str, Any]:
    ...
```

--------------------------------

### Quick Setup for Developers

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MODERNIZATION.md

Instructions for setting up the development environment.

```bash
# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Or use the Makefile
make setup
```

--------------------------------

### Development: Quick Start

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Instructions for cloning the repository and setting up the development environment.

```bash
# Clone with submodules
git clone --recurse-submodules https://github.com/aspectumapp/osm2geojson.git
cd osm2geojson

# One-command setup (installs deps + pre-commit hooks)
make setup
```

--------------------------------

### Verify Publication

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Commands to verify the publication on GitHub Actions and PyPI, and test installation.

```bash
pip install --upgrade osm2geojson
python -c "import osm2geojson; print(osm2geojson.__version__)"
```

--------------------------------

### Writing Tests (unittest)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Example of a unittest test case for testing a feature, using a fixture to get data and asserting dictionary equality.

```python
class TestSomething(unittest.TestCase):
    def test_feature(self):
        """Test that feature X works correctly."""
        data, expected = get_json_and_geojson_data('test-case-name')
        result = json2geojson(data)
        self.assertDictEqual(expected, result)
```

--------------------------------

### New setup command

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

The new, single command for setting up the project.

```bash
git clone --recurse-submodules https://github.com/aspectumapp/osm2geojson.git
cd osm2geojson
make setup         # One command!
make all           # Check everything
# Release via GitHub Release (automatic)
```

--------------------------------

### Testing - Writing Tests - Example with pytest

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Example of how to write a test using pytest and the available fixtures.

```python
def test_new_feature(get_json_and_geojson):
    """Test that feature X works correctly."""
    data, expected = get_json_and_geojson('test-case-name')
    result = json2geojson(data)
    assert result == expected

```

--------------------------------

### Push to GitHub

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Command to push the commit and tags to GitHub.

```bash
git push origin master --tags
```

--------------------------------

### Testing - Writing Tests - Example with unittest

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Example of how to write a test using unittest (legacy).

```python
def test_new_feature(self):
    data, expected = get_json_and_geojson_data('test-case-name')
    result = json2geojson(data)
    self.assertEqual(expected, result)

```

--------------------------------

### Installing with Development Dependencies

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MODERNIZATION.md

Command to install the package in editable mode with development dependencies.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Testing Pre-Release

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Steps to test a pre-release version using TestPyPI.

```text
1. Use TestPyPI: https://test.pypi.org/
2. Modify workflow temporarily to use TestPyPI
3. Test installation from TestPyPI
4. Switch back to production PyPI
```

--------------------------------

### Docstrings (Google Style)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Example of a Python function with Google-style docstrings, including Args, Returns, and Raises sections.

```python
def way_to_shape(
    way: dict,
    refs_index: dict = None,
    area_keys: Optional[dict] = None,
    raise_on_failure: bool = False
) -> Optional[dict]:
    """Convert an OSM way to a shape object.

    Args:
        way: OSM way element dictionary.
        refs_index: Index of referenced elements.
        area_keys: Custom area key configuration.
        raise_on_failure: Whether to raise exceptions on errors.

    Returns:
        Shape object with geometry and properties, or None if conversion fails.

    Raises:
        Exception: If raise_on_failure is True and conversion fails.
    """
    ...
```

--------------------------------

### Quick Reference Commands

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Common commands for setup, daily workflow, and debugging.

```bash
# Setup (one-time)
git clone --recurse-submodules https://github.com/aspectumapp/osm2geojson.git
cd osm2geojson
make setup              # Install deps + pre-commit hooks

# Daily workflow
make format             # Auto-format code
make lint               # Check code quality
make test               # Run tests
make all                # Run all checks (before committing!)

# Debugging
pytest tests/test_main.py::test_name -vv    # Run specific test
pytest --pdb                                 # Debug on failure
ruff check --diff .

```

--------------------------------

### Troubleshooting: Build Fails Locally

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Commands to clean the environment and retry the build.

```bash
make clean
pip install --upgrade build
python -m build
```

--------------------------------

### Writing Tests (pytest)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Example of a pytest test function using a fixture to get data and compare the result of json2geojson with the expected output.

```python
def test_feature(get_json_and_geojson):
    """Test that feature X works correctly."""
    data, expected = get_json_and_geojson('test-case-name')
    result = json2geojson(data)
    assert result == expected
```

--------------------------------

### Installation

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Install the osm2geojson library using pip.

```bash
pip install osm2geojson
```

--------------------------------

### Logging

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Basic Python logging setup and usage with different log levels (debug, info, warning, error).

```python
from logging import getLogger
logger = getLogger(__name__)

logger.debug('Detailed debug info')    # Verbose
logger.info('Important event')         # Normal
logger.warning('Something unexpected')  # Concerning
logger.error('Failed operation')       # Error
```

--------------------------------

### Example: Query Overpass API Directly

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

An example of constructing an Overpass QL query, calling the API, and converting the result to GeoJSON.

```python
import osm2geojson

# Overpass QL query
query = """
[out:json];
(
  node["amenity"="restaurant"](50.746,7.154,50.748,7.157);
  way["amenity"="restaurant"](50.746,7.154,50.748,7.157);
);
out body geom;
"""

result = osm2geojson.overpass_call(query)
geojson = osm2geojson.json2geojson(result)
```

--------------------------------

### Prepare the Release

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Commands to prepare the release by checking out the main branch, pulling latest changes, cleaning, and running all tests.

```bash
git checkout master
git pull origin master

make clean
make all
```

--------------------------------

### Code Style - Docstrings (Google Style)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Example of a function with a docstring following the Google style guide.

```python
def function_name(param1: str, param2: int = 0) -> bool:
    """Short description.

    Longer description if needed.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ValueError: When something is invalid.
    """
    ...

```

--------------------------------

### Pre-Commit Checklist

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

A checklist of commands and conditions to verify before committing code.

```bash
✅ Code formatted: make format
✅ Tests pass: make test
✅ Linting clean: make lint
✅ Type checking: make type-check
✅ All checks: make all
✅ Docs updated (if API changed)
✅ Tests added (if new feature)
✅ Commit message clear
```

--------------------------------

### Old lint.sh usage

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

Example of how the old lint.sh script was used.

```bash
./lint.sh
```

--------------------------------

### Command-Line Interface Usage

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

How to use osm2geojson as a command-line tool after installation.

```bash
osm2geojson --help
# or
python -m osm2geojson --help
```

--------------------------------

### Essential Commands

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

A list of standard Make commands for development tasks within the osm2geojson project.

```bash
make setup          # One-time setup (install deps + hooks)
make all            # Format, lint, type-check, test (run before committing)
make format         # Auto-format with Ruff
make lint           # Check code quality
make test           # Run test suite
make test-coverage  # Tests with coverage report
```

--------------------------------

### Bump Version (Manual Process)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Manual steps to update the version in pyproject.toml, commit, and tag.

```bash
vim pyproject.toml  # Change version = "0.3.0"

git add pyproject.toml
git commit -m "chore: bump version to 0.3.0"
git tag -a v0.3.0 -m "Release version 0.3.0"
```

--------------------------------

### Old release.sh usage

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

Example of how the old release.sh script was used for manual releases.

```bash
./release.sh       # Manual release
```

--------------------------------

### Project Structure

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

An overview of the directory and file structure for the osm2geojson project.

```tree
osm2geojson/
├── osm2geojson/              # Main package
│   ├── __init__.py          # Public API exports
│   ├── main.py              # Core conversion logic ⭐
│   ├── parse_xml.py         # XML parsing utilities
│   ├── helpers.py           # Helper functions
│   ├── __main__.py          # CLI interface
│   ├── *.json               # Config files (area keys, polygon features)
├── tests/                    # Test suite
│   ├── conftest.py          # Pytest fixtures
│   ├── test_main.py         # Main conversion tests
│   ├── test_parse_xml.py    # XML parser tests
│   ├── test_polygon_logic.py # Polygon detection tests
│   └── data/                # Test data (OSM/JSON/GeoJSON pairs)
├── pyproject.toml           # Project config ⭐⭐⭐
├── Makefile                 # Development commands
├── CONTRIBUTING.md          # Contributor guide
├── DEVELOPMENT_QUICKSTART.md # Command reference
└── AI_AGENT_GUIDE.md        # This file
```

--------------------------------

### Debugging Submodule Issues

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Commands to initialize and update git submodules.

```bash
# Initialize submodules
git submodule update --init --recursive

# Update to latest
./update-osm-polygon-features.sh
```

--------------------------------

### Bump Version (Recommended)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Script to automatically bump the version, update pyproject.toml, create a commit, and tag.

```bash
./bump_version.sh 0.3.0
```

--------------------------------

### Complete release workflow

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

A sequence of commands to perform a complete release, including cleaning, testing, version bumping, and pushing.

```bash
make clean
make all                           # Test everything
./bump_version.sh 0.3.0           # Updates pyproject.toml, commits, and tags
git push origin master --tags      # Push everything
# Then create GitHub Release (triggers PyPI publish)
```

--------------------------------

### Undo release steps

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Commands to undo the last commit and tag if needed before pushing.

```bash
git reset --hard HEAD~1
git tag -d v0.3.0
```

--------------------------------

### Example: Convert OSM XML to GeoJSON

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Demonstrates reading an OSM XML file and converting it to GeoJSON.

```python
import osm2geojson

with open('data.osm', 'r', encoding='utf-8') as f:
    xml = f.read()

geojson = osm2geojson.xml2geojson(xml, filter_used_refs=False, log_level='INFO')
# Returns: { "type": "FeatureCollection", "features": [ ... ] }
```

--------------------------------

### Code Style - Type Hints

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Example of using type hints in Python function signatures.

```python
from typing import Optional, List, Dict

def process_element(
    el: dict,
    refs_index: dict = None,
    raise_on_failure: bool = False
) -> Optional[dict]:
    """Process an OSM element."""
    ...

```

--------------------------------

### Release Notes Template

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

A template for release notes including sections for new features, bug fixes, documentation updates, internal changes, and contributors.

```markdown
## What's New in v0.2.10

### ✨ New Features
- Added support for X
- Improved Y performance

### 🐛 Bug Fixes
- Fixed issue with Z (#123)
- Resolved problem where...

### 📚 Documentation
- Updated contributor guide
- Added examples for...

### 🔧 Internal Changes
- Migrated to pyproject.toml
- Added type hints
- Improved test coverage

### 🙏 Contributors
Thanks to @username1, @username2 for their contributions!

**Full Changelog**: https://github.com/aspectumapp/osm2geojson/compare/v0.2.9...v0.2.10
```

--------------------------------

### Development: Run Specific Tests

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Examples of how to run specific tests using pytest, including by file, pattern, or with coverage.

```bash
# Single test (unittest-style class)
pytest tests/test_main.py::TestOsm2GeoJsonMethods::test_barrier_wall -vv

# Test file
pytest tests/test_main.py -vv

# By pattern
pytest -k barrier -vv

# With coverage
make test-coverage
```

--------------------------------

### Troubleshooting: Wrong Version Published (Yank)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/RELEASE_GUIDE.md

Commands to yank a previously published version and upload a new one.

```bash
pip install twine
twine upload --repository pypi --skip-existing dist/*
```

--------------------------------

### Helper Function: shape_to_feature

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Example of converting a Shape object to a GeoJSON Feature.

```python
import osm2geojson

feature = osm2geojson.shape_to_feature(
    shape_obj=shapely_shape_object,
    properties={'custom': 'property'}
)
```

--------------------------------

### Helper Function: overpass_call

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Example of executing an Overpass API query using the helper function.

```python
import osm2geojson

result = osm2geojson.overpass_call('[out:json];node(50.746,7.154,50.748,7.157);out;')
```

--------------------------------

### Example: Convert Overpass JSON to Shapes

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Shows how to load Overpass JSON data and convert it into Shapely Shape objects.

```python
import json
import osm2geojson

with open('overpass.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

shapes = osm2geojson.json2shapes(data)
# Returns: [ { "shape": <Shapely geometry>, "properties": {...} }, ... ]

# Access geometry and properties
for shape_obj in shapes:
    geometry = shape_obj['shape']      # Shapely object
    osm_tags = shape_obj['properties']['tags']
    print(f"Type: {geometry.geom_type}, Tags: {osm_tags}")
```

--------------------------------

### Debugging Conversion Logic

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Python code snippets to enable debug logging for conversion logic.

```python
# Enable debug logging
geojson = xml2geojson(xml_data, log_level='DEBUG')

# Or in code
import logging
logging.basicConfig(level=logging.DEBUG)
```

--------------------------------

### Pitfall 2: View specific linting issues

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to view specific linting issues that require manual fixing.

```bash
# If still failing, errors need manual fix
ruff check .  # See specific issues
```

--------------------------------

### Refactor Code: Ensure tests pass

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to run all tests as a baseline before refactoring code.

```bash
# Baseline
make test  # Run all tests
```

--------------------------------

### Add a Feature: Write tests first

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Python code snippet for writing a pytest test case for a new feature before implementation (TDD).

```python
def test_new_feature():
    result = new_feature(test_data)
    assert result == expected
```

--------------------------------

### Fix a Bug: Verify fix

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash commands to format code, run all tests, and perform a full verification using make targets.

```bash
# Verify fix
make format      # Format code
make test        # Run all tests
make all         # Full verification
```

--------------------------------

### Pitfall 1: Fix and commit after bypassing hooks

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash commands to fix pre-commit issues and commit them after bypassing hooks.

```bash
# Then fix later
make format
git add .
git commit -m "fix: apply linting"
```

--------------------------------

### Fix a Bug: Run specific test

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to run a specific pytest test.

```bash
# Run specific test
pytest tests/test_main.py::test_specific -v
```

--------------------------------

### Python API Usage

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Examples of converting OSM/Overpass data to GeoJSON and Shape objects using the Python API.

```python
import osm2geojson

# From Overpass JSON
geojson = osm2geojson.json2geojson(overpass_json)

# From OSM/Overpass XML
geojson = osm2geojson.xml2geojson(osm_xml)

# To Shape objects (Shapely geometries + properties)
shapes = osm2geojson.json2shapes(overpass_json)
shapes = osm2geojson.xml2shapes(osm_xml)
```

--------------------------------

### Refactor Code: Verify no regression

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to perform a full verification after making incremental changes during refactoring.

```bash
# After each change
make all   # Full verification
```

--------------------------------

### Add a Feature: Design the API

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Python code snippet showing how to define a new feature function within the osm2geojson/main.py file, including a docstring.

```python
# In osm2geojson/main.py
def new_feature(data, option=False):
    """New feature description."""
    ...
```

--------------------------------

### Fix a Bug: Find related tests

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to search for test files related to a specific test name.

```bash
# Find related tests
grep -r "test_name" tests/
```

--------------------------------

### Shape Object Structure

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

The internal data structure used for representing geometric shapes within the library.

```python
shape_obj = {
    'shape': Point|LineString|Polygon|MultiPolygon,  # Shapely geometry
    'properties': {
        'type': 'node'|'way'|'relation',
        'id': int,
        'tags': {...},  # OSM tags
        # ... other metadata
    }
}
```

--------------------------------

### Debugging Failing Tests

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Commands to run specific failing tests with verbose output, check for data changes, and debug with print statements.

```bash
# Run specific failing test with verbose output
pytest tests/test_main.py::test_name -vv --tb=short

# Check if test data changed
git diff tests/data/

# Debug with print statements (then remove them)
pytest tests/test_main.py::test_name -s  # -s shows print()
```

--------------------------------

### Pitfall 1: Fix a commit automatically

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to automatically fix pre-commit hook issues using the make format target.

```bash
# Fix automatically
make format
```

--------------------------------

### Checking Ruff Changes

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash commands to see what changes Ruff would make to the code without applying them, and to check specific linting rules.

```bash
# See diff without applying
ruff format --diff osm2geojson/main.py

# Check specific rules
ruff check --select=E,F osm2geojson/
```

--------------------------------

### Add a Feature: Add to public API

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Python code snippet showing how to add a new function to the public API by updating the __all__ list in osm2geojson/__init__.py.

```python
# In osm2geojson/__init__.py
__all__ = [
    ...,
    'new_feature',  # Add here
]
```

--------------------------------

### Pitfall 1: Bypass pre-commit hooks

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to bypass pre-commit hooks during a git commit, to be used only when absolutely necessary.

```bash
# Or bypass (only if absolutely necessary)
git commit --no-verify -m "WIP: work in progress"
```

--------------------------------

### Error Handling Pattern

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

A Python function demonstrating a common error handling pattern with try-except blocks, logging, and conditional re-raising of exceptions.

```python
def process_something(data, raise_on_failure=False):
    try:
        result = do_work(data)
        return result
    except Exception as e:
        message = f"Failed to process: {e}"
        warning(message)  # Log warning
        if raise_on_failure:
            raise Exception(message)  # Re-raise if requested
        return None  # Graceful failure by default
```

--------------------------------

### Pitfall 2: Auto-fix linting errors

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Bash command to automatically fix linting errors using the ruff check --fix command.

```bash
# Auto-fix what's possible
ruff check --fix .
```

--------------------------------

### Debugging Failing Tests (Verbose)

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Commands to run pytest with verbose output, show print statements, drop into a debugger on failure, and show local variables on failure.

```bash
# Verbose output
pytest tests/test_main.py::test_name -vv

# Show print statements
pytest tests/test_main.py::test_name -s

# Drop into debugger on failure
pytest tests/test_main.py::test_name --pdb

# Show locals on failure
pytest tests/test_main.py::test_name --showlocals
```

--------------------------------

### Debugging Type Checking Errors

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Commands to check specific files for type errors and common fixes like adding type hints or using Optional.

```bash
# Check specific file
mypy osm2geojson/main.py

# Common fixes:
# - Add type hints: def func(x: int) -> str:
# - Use Optional: Optional[dict] for nullable
# - Add type: ignore comment (last resort)
result = complex_call()  # type: ignore
```

--------------------------------

### Fix a Bug: Write failing test

Source: https://github.com/aspectumapp/osm2geojson/blob/master/AI_AGENT_GUIDE.md

Python code snippet for writing a new pytest test case that is expected to fail initially for a bug fix.

```python
def test_bug_fix_for_issue_123():
    """Regression test for issue #123."""
    data = {...}  # Minimal reproduction
    result = json2geojson(data)
    assert result['features'][0]['geometry']['type'] == 'Polygon'
```

--------------------------------

### Building with Python Build

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MODERNIZATION.md

Instructions for building the package using the modern `python -m build` command.

```bash
python -m build
```

--------------------------------

### New linting and formatting commands

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

Replacement commands for linting and formatting using make.

```bash
make lint          # Run linter (Ruff - much faster!)
make format        # Auto-format code
make all           # Run all checks
```

--------------------------------

### Testing release build with Make

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

Command to test the release build using Make.

```bash
make test-build    # Test the build
# See RELEASE_GUIDE.md for complete process
```

--------------------------------

### Makefile Commands

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MODERNIZATION.md

Common development tasks available via the Makefile.

```bash
make setup 	 # Complete development setup
make test 	 # Run tests
make lint 	 # Run linter
make format 	 # Format code
make clean 	 # Clean build artifacts
```

--------------------------------

### New release process via GitHub Actions

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

Steps to perform a release using GitHub Actions.

```bash
# Automated via GitHub Actions
git tag v0.2.10
git push origin v0.2.10
# Create GitHub Release → Automatically publishes to PyPI
```

--------------------------------

### Testing - Running Tests

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Various ways to run tests, including with coverage and for specific cases.

```bash
# Run all tests
make test
# or: pytest

# With coverage
make test-coverage
# or: pytest --cov=osm2geojson --cov-report=html

# Specific tests
pytest tests/test_main.py                        # File
pytest tests/test_main.py::TestClass::test_name  # Specific test
pytest -k test_barrier                           # By pattern
pytest -vv                                       # Verbose
pytest -s                                        # Show print statements
pytest --pdb                                     # Drop into debugger

```

--------------------------------

### Common Development Tasks

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MODERNIZATION.md

Common development tasks and their corresponding commands.

```bash
# Run tests
make test 	             # or: pytest

# Run tests with coverage
make test-coverage 	     # or: pytest --cov=osm2geojson --cov-report=html

# Format code
make format 	            # or: ruff format .

# Lint code
make lint 	            # or: ruff check .

# Type check
make type-check 	        # or: mypy osm2geojson

# Run all checks
make all 	               # Formats, lints, type checks, and tests
```

--------------------------------

### Development Workflow - Making Changes

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Steps for making changes, including branching, coding, testing, and committing.

```bash
1. **Create a branch**
   ```bash
   git checkout -b feature/your-feature-name
   # or: git checkout -b fix/bug-description
   ```

2. **Make changes**
   - Edit code
   - Add/update tests
   - Update documentation if needed

3. **Format & test**
   ```bash
   make format        # Auto-format
   make test          # Verify tests pass
   ```

4. **Commit**
   ```bash
   git add .
   git commit -m "feat: your change description"
   # Pre-commit hooks run automatically
   ```

5. **Push & create PR**
   ```bash
   git push origin feature/your-feature-name
   # Then create Pull Request on GitHub
   ```

```

--------------------------------

### Quick version bump

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

This script updates the version, commits the changes, and creates a tag. It is followed by a git push and a manual GitHub Release to publish to PyPI.

```bash
./bump_version.sh 0.3.0  # Updates version, commits, and tags
git push origin master --tags
# Then create GitHub Release to publish to PyPI
```

--------------------------------

### Run All Checks

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Makefile command to run all project checks, typically used before submitting a pull request.

```bash
make all
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Common commands for formatting, linting, testing, and checking code quality during development.

```bash
make format      # Auto-format code with Ruff
make lint        # Check code quality
make test        # Run tests with pytest
make all         # Run all checks (do this before committing!)
```

--------------------------------

### Ruff Formatting and Checking

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MODERNIZATION.md

Commands to format and check code using Ruff, which replaces flake8, isort, and black.

```bash
ruff format
```

```bash
ruff check
```

--------------------------------

### Code Quality Commands

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Commands for formatting, linting, and type-checking the code.

```bash
make format         # Auto-format with Ruff
make lint           # Lint with Ruff
make type-check     # Type check with mypy
make all            # All checks

```

--------------------------------

### Project Structure

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

The directory structure of the osm2geojson project.

```bash
osm2geojson/
├── osm2geojson/          # Main package
│   ├── main.py          # Core conversion logic
│   ├── parse_xml.py     # XML parsing
│   ├── helpers.py       # Helper functions
│   └── __main__.py      # CLI interface
├── tests/               # Test suite
│   ├── conftest.py      # Pytest fixtures
│   ├── test_*.py        # Test files
│   └── data/            # Test data (OSM/JSON/GeoJSON pairs)
├── pyproject.toml       # Project config
└── Makefile             # Development commands
```

--------------------------------

### Retrieving old scripts from git history

Source: https://github.com/aspectumapp/osm2geojson/blob/master/MIGRATION_NOTES.md

Commands to retrieve the old lint.sh and release.sh scripts from git history.

```bash
git show HEAD~1:lint.sh > lint.sh.old
git show HEAD~1:release.sh > release.sh.old
```

--------------------------------

### Check Linting Issues

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Ruff commands for checking and fixing linting issues, including diffing changes and checking specific files.

```bash
# See what would change
ruff format --diff .

# Auto-fix issues
ruff check --fix .

# Check specific file
ruff check osm2geojson/main.py
```

--------------------------------

### Debugging Tests

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

Pytest commands for debugging tests with verbose output, showing print statements, and dropping into a debugger on failure.

```bash
# Verbose output with full tracebacks
pytest tests/test_main.py::test_name -vv --tb=long

# Show print statements
pytest tests/test_main.py::test_name -s

# Drop into debugger on failure
pytest tests/test_main.py::test_name --pdb
```

--------------------------------

### Error Handling Pattern

Source: https://github.com/aspectumapp/osm2geojson/blob/master/CONTRIBUTING.md

A Python function demonstrating an error handling pattern with an option to raise exceptions on failure.

```python
def process(data, raise_on_failure=False):
    try:
        result = do_work(data)
        return result
    except Exception as e:
        message = f"Failed: {e}"
        warning(message)
        if raise_on_failure:
            raise Exception(message)
        return None
```

--------------------------------

### Development: Update Polygon Features

Source: https://github.com/aspectumapp/osm2geojson/blob/master/README.md

Command to update the OSM polygon features data.

```bash
./update-osm-polygon-features.sh
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.