dullfig/xml-pipeline
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
xml-pipeline/CONTRIBUTING.md
dullfig d97c24b1dd
Some checks failed
CI / test (3.11) (push) Has been cancelled
Details
CI / test (3.12) (push) Has been cancelled
Details
CI / test (3.13) (push) Has been cancelled
Details
CI / lint (push) Has been cancelled
Details
CI / typecheck (push) Has been cancelled
Details
Add message journal, graceful restart, and clean repo for public release 
Three workstreams implemented:

W1 (Repo Split): Remove proprietary BloxServer files and docs, update
pyproject.toml URLs to public GitHub, clean doc references, add CI
workflow (.github/workflows/ci.yml) and CONTRIBUTING.md.

W2 (Message Journal): Add DispatchHook protocol for dispatch lifecycle
events, SQLite-backed MessageJournal with WAL mode for certified-mail
delivery guarantees (PENDING→DISPATCHED→ACKED/FAILED), integrate hooks
into StreamPump._dispatch_to_handlers(), add journal REST endpoints,
and aiosqlite dependency.

W3 (Hot Deployment): Add RestartOrchestrator for graceful restart with
queue drain and journal stats collection, SIGHUP signal handler in CLI,
POST /organism/restart endpoint, restart-aware app lifespan with journal
recovery on boot, and os.execv/subprocess re-exec for Unix/Windows.

All 439 tests pass (37 new tests for W2/W3).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 22:27:38 -08:00

2.1 KiB
Raw Blame History

Contributing to xml-pipeline

Thank you for considering contributing to xml-pipeline.

Development Setup

git clone https://github.com/xml-pipeline/xml-pipeline.git
cd xml-pipeline
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

pip install -e ".[dev]"

Running Tests

pytest tests/ -v

Skip slow/integration tests:

pytest tests/ -v -m "not slow"

Code Style

This project uses ruff for linting and formatting, mypy for type checking.

ruff check xml_pipeline/ tests/
ruff format xml_pipeline/ tests/
mypy xml_pipeline/

All functions must have type hints. Async handlers use async def.

Pull Request Process

  1. Fork the repo and create a feature branch from main.
  2. Write tests for new functionality in tests/.
  3. Ensure pytest, ruff check, and mypy pass.
  4. Keep commits focused and write clear commit messages.
  5. Open a PR against main with a description of what changed and why.

Architecture

Read CLAUDE.md for the full architecture overview. Key principles:

  • XML is the sovereign wire format -- all messages are validated XML envelopes.
  • Handlers are untrusted -- the pump enforces identity, routing, and thread isolation.
  • Pipeline steps are composable -- add new processing stages by inserting async functions.
  • Async-first -- everything is async def, powered by aiostream.

Adding a New Pipeline Step

  1. Create xml_pipeline/message_bus/steps/your_step.py.
  2. Implement async def your_step(state: MessageState) -> MessageState.
  3. Insert into the pipeline in stream_pump.py build_pipeline().
  4. Add tests in tests/test_pipeline_steps.py.

Adding a New Handler

  1. Define a @xmlify @dataclass payload in your handler module.
  2. Write an async def handle_*(payload, metadata) -> HandlerResponse | None.
  3. Register in organism.yaml under listeners.
  4. See docs/handler-contract-v2.1.md for the full contract.

License

By contributing, you agree that your contributions will be licensed under the MIT License.