Development¶

This page covers all aspects of contributing to FABulous, including development environment setup, coding standards, and contribution workflows.

Development Environment Setup¶

Contributors must use uv for reproducible environment management and to ensure consistent dependency resolution with CI.

Installing uv¶

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your shell or source the env snippet the installer prints.

macOS with Homebrew:

brew install uv

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

PyPI:

pip install uv

Setting up the development environment¶

Clone the repository and set up the development environment:

git clone https://github.com/FPGA-Research/FABulous
cd FABulous
uv sync --dev                # install runtime + dev dependencies (locked)
uv pip install -e .          # editable install
source .venv/bin/activate    # activate the environment (optional)

Note

After running uv sync, uv creates a virtual environment in .venv/. You can either:

Use uv run <command> for each command (recommended for reproducibility)
Activate the environment with source .venv/bin/activate and run commands directly

Common development commands:

# Using uv run:
uv run FABulous -h           # run CLI with project dependencies
uv run pytest               # run test suite
uv run pytest -k test_name  # run specific test
uv run ruff check           # lint code
uv run ruff format          # format code

# Or with activated environment:
(.venv) $ FABulous -h
(.venv) $ pytest
(.venv) $ ruff check
(.venv) $ ruff format

Dependency management:

uv add <package>             # add runtime dependency
uv add --group dev <package> # add development dependency
uv remove <package>          # remove dependency
uv lock                      # refresh lock file after manual edits

Pre-commit Hooks¶

We use pre-commit hooks to maintain code quality. These hooks automatically run formatters and linters before each commit.

Install pre-commit hooks:

uv run pre-commit install

The hooks will now run automatically on git commit. You can also run them manually:

uv run pre-commit run --all-files

If you need to bypass the hooks temporarily (not recommended):

git commit --no-verify

Task Automation with Taskipy¶

FABulous includes pre-configured taskipy tasks to streamline common development and workflow tasks. After setting up the development environment, you can run these tasks using task <task-name>.

Development and Quality Tasks¶

task format          # Format code with ruff
task lint            # Lint and fix code issues + run pre-commit
task check           # Check code without fixing
task qa              # Run format and check in sequence
task pre-commit      # Run format and check (for pre-commit hooks)
task ci-check        # Full CI check (format, lint, test, docs)
task install-dev     # Install development dependencies
task clean-all       # Clean all build artifacts and cache files

Documentation Tasks¶

task docs-setup      # Setup documentation environment
task docs-apidoc     # Generate API documentation only
task docs-build      # Generate API docs + build documentation
task docs-server     # serve docs with live reload for development
task docs-clean      # Clean documentation build artifacts

Project Creation and Setup¶

task fab-proj               # Create demo project

FABulous Workflow Tasks¶

# Fabric generation and simulation
task fab-build              # Create demo project + run FABulous fabric generation
task fab-build-clean        # Clean build + create project + run fabric generation
task fab-sim                # Create demo project + run full simulation
task fab-sim-clean          # Clean build + create project + run simulation

Example Development Workflows¶

Standard development workflow:

# Format and check your code
task qa

# Run full CI validation before submitting PR
task ci-check

Quick FABulous testing:

# Create demo project and test fabric generation
task fab-build

# Run full simulation workflow
task fab-sim

Documentation development:

# Setup docs environment (first time)
task docs-setup

# Build and serve docs with auto-reload
task docs-server

Clean development environment:

# Clean all build artifacts and caches
$ task clean-all

Note

The taskipy tasks are defined in the [tool.taskipy.tasks] section of pyproject.toml. You can view all available tasks by running task --list or examine the configuration in the project’s pyproject.toml file.

Code Standards¶

Code Formatting¶

We use Ruff for both linting and formatting. The configuration is defined in ruff.toml in the repository root.

Format your code before committing:

uv run ruff format

Check for linting issues:

uv run ruff check
uv run ruff check --fix  # auto-fix issues where possible

Documentation Style¶

Follow numpy docstring style
Keep docstrings concise but complete
Include examples for complex functions
Update documentation when changing APIs

Testing¶

Write tests for new functionality
Ensure existing tests pass before submitting PRs
Run the full test suite: uv run pytest
Check test coverage where applicable

Contribution Workflow¶

We follow a standard Git workflow for contributions. Please ensure you’re familiar with this process before contributing.

Getting Started¶

Check the issues and the latest commits at the FABulous main branch to see if your feature or bug fix has already been reported or implemented.
Fork the repository on GitHub.
Clone your forked repository to your local machine.
Use the latest version of the main branch as base for your work.

Making Changes¶

Create a new branch for your feature or bug fix:
```
git checkout -b feature/your-feature-name
```
Set up the development environment as described above.
Make your changes, following the coding standards outlined in this document.
Write or update tests as necessary.
Ensure all tests pass and code is properly formatted.
Commit your changes with clear, descriptive commit messages using the conventional commits style.

Submitting Changes¶

Push your changes to your forked repository:
```
git push origin feature/your-feature-name
```
Submit a pull request to the main repository.
Ensure your pull request targets the main branch of the original repository.
Check that your pull request passes all CI checks. If it does not, please fix the issues first.
We will review your pull request and may request changes or provide feedback. Please be responsive to these requests.

Commit Message Style¶

We use the conventional commits style for commit messages and pull requests. This helps us automatically generate changelogs and understand the history of changes better.

Format: <type>[(<optional scope>)]: <description>

Examples:

feat: add support for new tile type
fix: resolve bitstream generation issue
docs: update installation instructions
test: add integration tests for fabric generator
chore(ci): update workflow

Types:

feat: new feature
fix: bug fix
docs: documentation changes
test: adding or updating tests
refactor: code refactoring
perf: performance improvements
chore: maintenance tasks

Development Notes¶

Environment Management¶

Always use uv for development to ensure dependency resolution is consistent with CI
Issues arising only under ad-hoc pip environments may be closed with a request to reproduce under uv
The uv.lock file is the authoritative source for exact dependency versions
When adding dependencies, prefer adding them via uv add rather than manually editing pyproject.toml

Project Structure¶

Development dependencies are defined in the [dependency-groups] section of pyproject.toml
Regular dependencies are in the [project] dependencies list
Test configuration is in [tool.pytest.ini_options] in pyproject.toml
Pre-commit configuration is in .pre-commit-config.yaml

CI/CD¶

All pull requests must pass CI checks
CI runs tests, linting, and formatting checks
CI uses the same uv-based environment as local development
Lock file changes are automatically validated

License¶

By contributing to this project, you agree that your contributions will be licensed under the project’s Apache 2.0 License.