Skip to content

🤝 Contributing & Development Guidelines

Thank you for your interest in contributing to Tabularix! This document provides instructions for setting up your local environment, running static analysis checks, executing test suites, and preparing packages for release.

🛠️ Environment Setup

Tabularix is a hybrid library with a high-performance Rust core and Python bindings.

The easiest and recommended way to get started is by using VS Code Dev Containers. The project includes a fully configured .devcontainer directory containing all necessary compilers, Python versions, formatters, and linters pre-installed.

  1. Clone the Repository: 
    git clone https://github.com/pcasteran/tabularix.git
cd tabularix
  2. Open in VS Code: Open the folder in VS Code, and click the "Reopen in Container" prompt.

2. Manual Environment Setup (Alternative)

If you prefer to configure your environment manually, local toolchains installation is managed using mise.

  1. Install Global Prerequisites:

Mise usage

To run development commands directly (e.g. just build), you can activate mise in your current shell session by running eval "$(mise activate bash)" (or equivalent for your shell). Otherwise, prefix the commands with mise exec -- (e.g. mise exec -- just build). The examples below assume mise has been activated.

  1. Clone the Repository:

    git clone https://github.com/pcasteran/tabularix.git
cd tabularix

  2. Set Up Toolchains: Install all correct compilers, runtimes, and linters defined in mise.toml:

    mise install

  3. Build the Project: Compile the Rust engine extension and build the Python wheel: 

    just build

🔍 Code Style & Static Analysis

We enforce strict formatting and quality checks across all files. Always run the static analysis suite before submitting code:

# Execute all pre-commit hooks, formatting, and linters.
just prek

# Update the static analysis engine and hook versions.
just prek-hooks-update

The just prek command validates:

  • Rust formatting (cargo fmt) and linting (cargo clippy).
  • Python linting/formatting (ruff).
  • JSON, YAML, and TOML validation.
  • Markdown and spellchecking.

🧪 Testing Suites

All contributions must pass the entire test suite before merging.

# Run Rust unit tests.
just unit-test

# Run Robot Framework acceptance tests.
just acceptance-test

📖 Building Documentation

The documentation site is powered by Zensical.

# Run a local development documentation server.
just docs-serve

# Build the static HTML site (output to site/ directory).
just docs-build

📦 Release Preparation

If you are preparing a new release, use the automated recipe to branch, update the changelog, and bump versions:

# Calculate next version, branch, update CHANGELOG.md, and bump versions.
just prepare-release

🔄 Release Rollback Action Plan

In the event of a critical issue discovered immediately after a package release, follow these steps to yank the release and prevent installation of the broken package version.

1. Yank the Package on PyPI

Yanking a package marks the version as broken. It prevents pip install from installing it by default, but does not break existing dependencies that explicitly pin to the exact version.

  • Via PyPI Web Interface:
    1. Log in to PyPI.
    2. Navigate to Project -> tabularix -> Manage.
    3. Select Options next to the specific version (e.g. 0.1.0).
    4. Click Yank Release and provide a reason (e.g., critical regression).

2. Delete the Git Tag

Delete the git tag locally and remotely to prevent the CI/CD pipeline from referencing the broken release tag:

# Delete local tag
git tag -d v0.1.0

# Delete remote tag
git push --delete origin v0.1.0

3. Deploy a Hotfix Release

  1. Create a hotfix branch from main (e.g. chore/release-v0.1.1).
  2. Fix the regression and verify that all unit/acceptance tests pass cleanly.
  3. Update version metadata and CHANGELOG.
  4. Merge the PR, pull the changes to main, and push the new tag (e.g. v0.1.1) to trigger the CI/CD release workflow.