Contributor’s Guide

Interested in contributing to Vaibify? This page outlines the steps to make a meaningful contribution. Before you begin, contact Rory Barnes to confirm that your proposed changes are not duplicating work and will be of general interest.

Style Guide

Vaibify follows the style conventions described in the project’s global development standards. The key rules are summarized here.

Naming Conventions

  • Variables use camelCase with Hungarian prefixes: bEnabled, iCount, sName, fValue, daWeights, dictConfig, listItems.

  • Functions begin with f followed by lowercase letter(s) indicating the return type: fbIsValid(), fsGetName(), fnRunStep() (no return).

  • Files use camelCase without Hungarian prefixes: pipelineRunner.py, containerManager.py.

Functions

  • Functions should be fewer than 20 lines.

  • Each function should have a single, clear purpose.

  • If the same lines appear in multiple places, extract them into a new function.

Code Clarity

  • Variable and function names should be self-explanatory.

  • Use inline comments sparingly – clear naming replaces most comments.

  • Do not abbreviate any word shorter than 8 characters.

  • Function names must contain an action verb (except main).

Running Tests

Run the full test suite:

pytest tests/

Run only tests that require Docker:

pytest -m docker

Run with coverage:

pytest --cov=vaibify tests/

Portability and CI

All code must work on both macOS and Linux, and with Python versions 3.9 through 3.14. GitHub Actions runs unit tests on every pull request across all permutations of Ubuntu 22.04/24.04, macOS 15/26, and Python 3.9 through 3.14. Tests that require a running Docker daemon are excluded from CI and run locally. Documentation is rebuilt and deployed automatically on every merge to main.

Pull Request Workflow

  1. Fork the repository and create a feature branch.

  2. Make your changes following the style guide.

  3. Add or update tests as needed.

  4. Run pytest locally and confirm all tests pass.

  5. Open a pull request against the main branch with a clear description of the change.

Project Layout

vaibify/
  cli/                Command-line interface (Click)
  config/             Configuration dataclasses and parsers
  docker/             Container lifecycle management
  gui/                FastAPI web application and pipeline runner
    routes/           12 route modules (stepRoutes, fileRoutes, etc.)
    static/           24 JavaScript IIFE modules + CSS + HTML
    pipelineServer.py App factory, shared utilities, WebSocket dispatch
    pipelineRunner.py Pipeline step execution orchestrator
    pipelineUtils.py  Shared leaf utilities (fsShellQuote, emitters)
    workflowManager.py Workflow CRUD, variable resolution, dependency graph
    fileStatusManager.py File polling, mtime tracking, step invalidation
    testGenerator.py  Test generation orchestrator
    dataLoaders.py    Data format dispatch table (50 extensions)
    syncDispatcher.py Sync operations (GitHub, Overleaf, Zenodo)
    ...               See CLAUDE.md at repo root for the full module map
  install/            Setup wizard and shell installer
  reproducibility/    Zenodo, Overleaf, and LaTeX integration
templates/            Project templates (sandbox, workflow)
tests/                Pytest test suite (2,200+ tests)
docs/                 Sphinx documentation (this site)
CLAUDE.md             Architecture guide with module map and data flows

For a detailed architecture overview including module dependency graphs, state management patterns, and data flow diagrams, see CLAUDE.md at the repository root.