Skip to content

Contribute

Contributing to Waldiez Projects

Thank you for your interest in contributing to our projects! This document outlines the guidelines for contributing to Waldiez projects, including how to report issues, submit code changes, and adhere to our code of conduct.

[Project Specific Guidelines]

This project consists of two components:

  • A Python package, located in the waldiez folder, built using hatch
  • A TypeScript (React) library and web application, located in the src folder, built using bun

🐍 Contributing to the Python Part (waldiez/)

The Python backend is a package managed primarily using Hatch, with optional support for uv and plain venv.

  1. Install Hatch:
pip install hatch
  1. Create the dev environment:
hatch env create
hatch shell
  1. All optional dependencies are managed via extras (dev, test, docs, etc.), and available via:
hatch run pip list

⚡ Alternative: Fast Setup with uv

  1. Install uv:
pip install uv
  1. Create and activate an environment:
uv venv --python 3.12
source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
  1. Install extras:
uv pip install '.[dev,test,docs]'

🔧 Alternative: Plain Python with venv and requirements/

This project also supports traditional requirements-based setup:

  1. Create a virtualenv:
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
  1. Install dependencies:
pip install -r requirements/all.txt
# or (to manually select what you need):
pip install -r requirements/dev.txt
pip install -r requirements/test.txt
pip install -r requirements/docs.txt

If using this method, you won’t have access to Hatch’s hatch run commands. Instead, use:

python scripts/lint.py python scripts/test.py python scripts/format.py python scripts/build.py

Or you prefer make, you can use make commands:

Usage: make [target]

Default target: help

Targets:
 help             Show this message and exit
 requirements     Generate requirements/*.txt files
 format           Run the formatters for the python package
 lint             Run the linters for the python package
 forlint          Alias for 'format' and 'lint'
 clean            Cleanup unneeded files
 test             Run the tests for the python package
 test-models      Run the tests for the models
 test-exporting   Run the tests for exporting
 test-running     Run the tests for running
 test-io          Run the tests for the IO stream
 build            Build the python package
 docs             Generate the python documentation
 docs-live        Generate the documentation in 'live' mode
 images           Build the podman/docker images
 some             Run some (not all) of the above

🧪 Testing (Python)

To run all tests with full coverage reports:

hatch run test

To run only selected test modules:

hatch run test-models
hatch run test-exporting
hatch run test-io

To test against multiple Python versions (3.10–3.13):

hatch run matrix-test

🧹 Formatting & Linting (Python)

To auto-format everything:

hatch run format

To run all linters:

hatch run lint

This runs: black, ruff, mypy, flake8, bandit, pylint, yamllint

📦 Build & Release (Python)

To generate build artifacts:

hatch run build

To generate the documentation:

Note: For the "full" documentation (and the react related parts), we should first generate the React markdown files using bun docs. Then, we can generate the full documentation using:

hatch run docs

To run all checks + matrix tests + docs + build:

hatch run all

⚛️ Contributing to the React Part (src/)

The React frontend is a TypeScript project built with Bun, and Vite. It includes integrated support for Monaco editor, Playwright browser testing, Vitest, and full lint/style/format scripts.

🧰 Prerequisites

  • Node.js 22.x or later
  • Bun v1.2.11 or later

🚀 Setup

  1. Clone the repository if not already done:
git clone https://github.com/waldiez/waldiez.git -b dev
cd waldiez
  1. Install the dependencies:
bun install

🧪 Development (React)

Start the dev server:

bun dev

This runs bun monaco && vite and launches the app at:

http://localhost:5173

🧹 Formatting & Linting (React)

To check and fix code style:

bun format

This runs:

  • prettier
  • stylelint
  • eslint --fix

To check only (no changes):

bun lint

Or do both:

bun forlint

🧪 Testing (React)

Run all tests (components + browser):

bun test

Run just unit/component tests:

bun test:components

Run browser tests (Playwright required):

bun test:browser

Update UI snapshots:

bun test:snapshots

Run tests with coverage:

bun test:coverage

📦 Build (React)

Full build pipeline (library + web app + archive):

bun run build

Build documentation (this will only generate the React markdown files in docs/reference/react):

bun docs

Preview build output:

bun preview

🔧 Cleaning (React)

Clean all outputs (builds, coverage, tsbuildinfo, etc.):

bun clean

You can also run partial cleaning scripts:

  • bun clean:lintcache
  • bun clean:dist
  • bun clean:coverage
  • bun clean:web
  • bun clean:docs
  • bun clean:archive

🔗 Combined Project Pipeline

You can run the full project build pipeline (React + Python) using the unified helpers:

# or ./scripts/do.{sh,ps1} all
python do.py all
# or:
node --import=tsx do.ts all  # or npx tsx do.ts all

This will:

  • Format, lint, and test the React project
  • Build the React frontend and archive
  • Format, lint, and test the Python package
  • Build the Python wheel/sdist
  • Build documentation
  • Build a Docker image with the python package

✅ Submitting Changes

  1. Ensure lint and tests pass:
# either on the react part:
bun format
bun lint
bun test
bun schema
# or on the python part:
hatch run format
hatch run lint
hatch run test
# or the make/python way:
make forlint
make test
  1. Optionally (but recommended) ensure everything (Python + React) is working:
# or ./scripts/do.{sh,ps1} all
./do all
  1. Commit and push:
git commit -m "feat: my feature"
git push origin feature/my-feature
  1. Open a pull request targeting the dev branch.

💡 Tip: All low-level commands are also available in scripts/, such as:

  • scripts/do.sh
  • scripts/do.ps1
  • scripts/monaco.ts
  • scripts/changelog.ts
  • scripts/mkdir.ts
  • scripts/pack.ts
  • scripts/schema.ts
  • scripts/image.py
  • scripts/format.py
  • scripts/lint.py
  • scripts/test.py
  • scripts/build.py

Code of Conduct

We expect all contributors to adhere to our Code of Conduct. Please read it carefully and ensure that your contributions align with our community values.

Reporting Issues

If you encounter any issues while using our projects, please report them to the relevant Project's issue tracker. When reporting an issue, please provide as much detail as possible, including:

  • A clear and descriptive title for the issue
  • A detailed description of the problem
  • Steps to reproduce the issue
  • Any relevant screenshots or error messages
  • Your environment details (e.g., operating system, version, etc.)
  • Any other information that may help us understand the issue

Submitting Code Changes

If you would like to contribute code changes, please follow these steps:

  1. Fork the repository (prefer the dev branch if available) and create a new branch for your changes.
  2. Work on your changes in the new branch. Ensure that your code adheres to our coding standards and best practices.
  3. Run tests to ensure that your changes do not introduce any new issues.
  4. Submit a pull request to the dev (or main a dev is not available) branch of the original repository.
  5. Include a description of your changes and reference any related issues in the pull request.
  6. Ensure that your pull request passes all checks and adheres to our contribution guidelines.
  7. Be responsive to feedback and make any necessary changes to your pull request.
  8. Once your pull request is approved, it will be merged into the main branch.
  9. Celebrate your contribution to the Waldiez community!

Contributor License Agreement (CLA)

By submitting code changes, you agree to the terms of our Contributor License Agreement (CLA). Please read the CLA carefully before submitting your changes. If you have any questions or concerns about the CLA, please contact us, and we will be happy to assist you.

Developer Certificate of Origin (DCO)

By contributing to a project owned by Waldiez, you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution.

Security Policy

If you discover a security vulnerability in any of our projects, please report it to us immediately. Do not disclose the vulnerability publicly until we have had a chance to address it. For more information, please refer to our Security Policy.

License

By contributing to Waldiez projects, you agree to the terms of our License. Please read the license carefully before submitting your contributions. If you have any questions or concerns about the license, please contact us, and we will be happy to assist you.