Contributing

This document provides guidelines for contributing to the Corsair project.

Getting Started

The recommended way to develop Corsair is using the provided Devcontainer configuration, which ensures a consistent environment with all necessary dependencies.

Option 1: VS Code + Dev Containers (Recommended)

1. Prerequisites: Install Docker Desktop and Visual Studio Code with the Dev Containers extension.
2. Clone the repository: git clone https://github.com/esynr3z/corsair.git
3. Open in VS Code: Open the cloned corsair folder in VS Code.
4. Reopen in Container: VS Code should prompt you to "Reopen in Container". Click it. Alternatively, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P), search for "Dev Containers: Reopen in Container", and run the command.
5. Wait: The first time, it will take a few minutes to build the Docker image and set up the container.
6. Verify: Once the container is ready, open a terminal within VS Code (Terminal > New Terminal). It should open inside the dev container. Verify by running:

   uv run corsair --help
   

   You should see the Corsair CLI help message.

Option 2: Using Docker CLI

1. Prerequisites: Install Docker.
2. Clone the repository: git clone https://github.com/esynr3z/corsair.git
3. Navigate: cd corsair
4. Build the image: Build the Docker image using the provided Dockerfile.

   docker build -t corsair-dev .devcontainer/
   

5. Run the container: Start an interactive container, mounting the project directory.

   Linux/macOSWindows (Command Prompt)Windows (PowerShell)

   docker run -it --rm -v "$(pwd):/workspaces/corsair" -w /workspaces/corsair corsair-dev bash
   

   docker run -it --rm -v "%cd%:/workspaces/corsair" -w /workspaces/corsair corsair-dev bash
   

   docker run -it --rm -v "${PWD}:/workspaces/corsair" -w /workspaces/corsair corsair-dev bash
   

   • -it: Interactive terminal.
   • --rm: Remove the container when it exits.
   • -v "...:/workspaces/corsair": Mounts your local project directory into the container.
   • -w /workspaces/corsair: Sets the working directory inside the container.
   • corsair-dev: The image name we built.
   • bash: The command to run inside the container.
   • Setup Environment: Inside the container's bash prompt, install dependencies and pre-commit hooks:

     uv sync --all-extras --dev
     uv run poe install-hooks
     

   • Verify: Inside the container's bash prompt, run:

     uv run corsair --help
     

     You should see the Corsair CLI help message.

Running Commands

Once inside the development environment (either VS Code terminal or Docker bash), use uv run to execute commands within the project's managed Python environment. This ensures you are using the correct dependencies.

For example, to run pytest:

uv run pytest

Available Tasks (Poe the Poet)

Common development tasks are defined using poethepoet and can be run via uv run poe <task_name>. You can list all available tasks with:

uv run poe

Common tasks include:

• clean: Clean project directory from temporary files and folders
• install-hooks: Install Git pre-commit hooks
• format: Format all the Python code with Ruff
• lint: Lint all the Python code with Ruff
• fix-lint: Lint all the Python code with Ruff and fix the issues
• check-format: Check format for all the Python code with Ruff
• check-types: Do type checking for all the Python code with Pyright
• test: Run all tests via pytest
• test-cov: Run all tests via pytest with coverage collection
• check-commits: Do commit message checking for the current branch
• docs: Build the documentation
• serve-docs: Run development server for the documentation development

Project Choices

To ensure consistency and maintainability, the Corsair project relies on a specific set of tools and conventions. Understanding these choices is crucial for effective contribution.

Main Dependencies

• CLI Management: Typer
• Data Management: Pydantic
• Templating: Jinja2

Python Infrastructure

• Python Version: Requires Python 3.10 or newer.
• Package Management: uv
• Task Management: poethepoet (tasks defined in pyproject.toml)
• Formatting: Ruff Formatter
• Linting: Ruff Linter
• Type Checking: Pyright
• Unit Testing: pytest

HDL Infrastructure

• Unit Testing: cocotb
• Verilog/SystemVerilog Simulators: Verilator (open-source) and Modelsim (commercial).
• VHDL Simulators: GHDL (open-source) and Modelsim (commercial).
• Formal Verification: EQY (Yosys-SMTBMC)

Documentation

• Generator: MkDocs
• Theme: Material for MkDocs
• Hosting: GitHub Pages

Git Workflow

• Branching: A single master branch holds the stable code. Development happens in short-lived feature branches branched off master.
• Commits: Follow the Conventional Commits specification (checked via Commitizen).
• Tags: Follow Semantic Versioning (SemVer).
• Hooks: pre-commit (configured in .pre-commit-config.yaml).
• Changelog: Follow the Keep a Changelog format (in CHANGELOG.md).

Automation

• Continuous Integration (CI): GitHub Actions (configured in .github/workflows/).
• Development Environment: Devcontainer (configured in .devcontainer/devcontainer.json).