Contributing Code

Parts adapted from the Mesa Contributor Policy.

We’d love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.

Branching

For various reasons, it’s recommended to call working branches, even in your forks, something else other than master, main, or dev as these branch names do have some special behavior associated with them.

Note

The main branch is the stable branch for LibreLane, i.e., this branch is updated less frequently and only accepts bugfixes.

Feature contributions should be directed towards the dev branch.

Testing

Before you submit your changes, it’s prudent to perform some kind of smoke test. python3 -m librelane ./designs/spm/config.json tests a simple spm design to ensure nothing has gone horribly wrong.

Language Standards

Python

Python code should be written for Python 3.10+, and be typed. i.e., we require explicit type annotations for all major API functions.

You will need to ensure that your Python code passes linting with our three chosen tools (and one optional tool):

Tool

Kind

Command

Description

black

Formatter

black .

Ensures indentation and whitespace follow a strict standard without having you lift a finger.

flake8

Linter

flake8 .

Finds a number of common programming pitfalls.

mypy

Type-Checker

mypy .

Ensures that you’re using compatible types, i.e., you are not passing a string to a function that accepts an int, or passing None to a non-optional variable, and such.

ruff (optional)

Linter

ruff check .

Our pyproject.toml uses ruff as a simple parsing checker, i.e., makes sure your code can still parse under Python 3.8 as it is entirely too easy to write code that by accident only works on later versions of Python. We presently do not use other features of ruff.

Do all arithmetic either in integers or using the Python decimal library. All (numerous) existing uses of IEEE-754 are bugs we are interested in fixing.

Tcl

Only use Tcl to interface with tools that only have a Tcl interface (or have an immature Python interface)- i.e., Yosys, OpenROAD and Magic.

1TBS-indented, four spaces, lower_snake_case for local/global variables and UPPER_SNAKE_CASE for environment variables. Unfortunately it is impossible to add any other guidelines or standards to the Tcl code considering it is Tcl code. Please exercise your best judgment.

Yosys, OpenROAD and Magic Scripts

There are some special guidelines for scripts in scripts/yosys, scripts/openroad, and scripts/magic:

  • The scripts for each tool are a self-contained ecosystem: do not source scripts from outside their directories.

    • You may duplicate functionality if you deem it necessary.

  • Do not reference the following environment variables anywhere in order to avoid causing recursion when generating issue reproducibles:

    • $PWD

    • $RUN_DIR

    • $DESIGN_DIR

Submissions

Make your changes and then submit them as a pull requests to the:

  • main branch: For bugfixes.

  • dev branch: For new features.

Consult GitHub Help for more information on using pull requests.

You need to understand what code you are changing, what the change does, and justify that change in the commit messages and PR. Using coding assistants or “Generative AI” software or similar tools does not grant additional concessions and low-quality code typical thereof will be rejected outright.

The Approval Process

For a PR to be merged, there are two requirements:

  • There are two automated checks, one for linting and the other for functionality. Both must pass.

  • An LibreLane team member must inspect and approve the PR.