Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (47 loc) · 2.83 KB

CONTRIBUTING.md

File metadata and controls

73 lines (47 loc) · 2.83 KB
Raw

Contributing to pyegeria

First off, thank you for considering contributing to pyegeria! It's people like you that make Egeria a great tool for the metadata community.

Development Setup

We use uv for dependency management. To set up your environment:

  1. Clone the repository.
  2. Install dependencies: uv sync.
  3. Activate the environment: source .venv/bin/activate (macOS/Linux) or .venv\Scripts\activate (Windows).

Project Structure

  • pyegeria/core: Foundation clients and base classes.
  • pyegeria/omvs: Individual View Service implementations.
  • pyegeria/models: Pydantic models for Egeria API requests/responses.
  • pyegeria/view: Formatting logic (Markdown, Rich, Mermaid).
  • commands/: CLI tools and scripts.

Coding Standards

Sync and Async

Every new OMVS method should provide both an async version (prefixed with _async_) and a synchronous wrapper. This ensures compatibility with both high-performance applications and interactive Jupyter notebooks.

The wrapper calls run_sync from pyegeria.core.async_runner:

@dynamic_catch
def find_widgets(self, search_string: str = "*", ...) -> list | str:
    """Find widgets. See `_async_find_widgets`."""
    return run_sync(self._async_find_widgets(search_string, ...))

Don't use asyncio.run(...) or asyncio.get_event_loop().run_until_complete(...). Both fail when the caller already has a running event loop (Jupyter, Textual, FastAPI), and tests/micro-tests/test_async_runner.py fails if either appears in pyegeria/ or md_processing/. See Sync and async for how callers choose between the two forms.

Docstrings

We use the NumPy/SciPy docstring format. Ensure every public method has clear parameter descriptions and a "Notes" section with a sample JSON body where applicable.

Testing

We use pytest. We prioritize Scenario Tests that demonstrate full lifecycles (Create -> Link -> Detach -> Delete).

To run tests: pytest tests/

To run against a live Egeria instance: pytest --live-egeria (Requires environment variables for credentials).

Pull Request Process

Developer Certificate of Origin (DCO)

All contributions to this project must be accompanied by a Developer Certificate of Origin (DCO) sign-off. This is a formal declaration that you have the right to submit the code under the project's license.

To sign off on a commit, use the -s or --signoff flag:

git commit -s -m "Your commit message"

This will add a Signed-off-by: Your Name <your.email@example.com> line to your commit message.

Submission Steps

  1. Create a feature branch.
  2. Ensure unit and scenario tests pass.
  3. Update the EgeriaTech client if adding a new OMVS.
  4. Submit your PR for review.