Skip to content

Latest commit

 

History

History
232 lines (157 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

232 lines (157 loc) · 5.43 KB
Raw

Contribution Guide

This project runs on python>=3.8,<3.13

Setup

We use PDM as a dependency manager. Check the updated installation instructions from here, or follow these steps:

Linux/MAC:

# Install PDM Linux/MAC

curl -sSL https://pdm-project.org/install-pdm.py | python3 -

Windows:

# Install PDM Windows

(Invoke-WebRequest -Uri https://pdm-project.org/install-pdm.py -UseBasicParsing).Content | python -

Add PATH to environment manager and then run the appropriate command to install all the dependencies based on your Python version and operating system:

For Python 3.8

Linux:

pdm install --lockfile=pdm-py38unix.lock

Windows:

pdm install --lockfile=pdm-py38win.lock

macOS: If you are using macOS with Python 3.8, you need to manually install the vtk package due to compatibility issues. You can do this by running the following command:

pip install https://files.pythonhosted.org/packages/b3/15/40f8264f1b5379f12caf0e5153006a61c1f808937877c996e907610e8f23/vtk-9.3.1-cp38-cp38-macosx_10_10_x86_64.whl
```shell
pdm install --lockfile=pdm-py38macos.lock

For Python 3.9 and above

Linux:

pdm install --lockfile=pdm-py39+unix.lock

Windows:

pdm install --lockfile=pdm-py39+win.lock

macOS:

pdm install --lockfile=pdm-py39+macos.lock

Using requirements.txt files

The corresponding requirements.txt files are generated during pre-commit hooks and located in the /requirements folder.

Adding new packages

When adding a new package, make sure to update the correct lock file(s). For example:

For Python 3.8 Windows

pdm add <package_name> --lockfile=pdm-py38win.lock

For Python 3.8 Linux

pdm add <package_name> --lockfile=pdm-py38unix.lock

For Python 3.8 (macOS):

pdm add <package_name> --lockfile=pdm-py38macos.lock

For Python 3.9+ Linux

pdm add <package_name> --lockfile=pdm-py39+unix.lock

For Python 3.9+ (macOS):

pdm add <package_name> --lockfile=pdm-py39+macos.lock

Remember to update all relevant lock files when adding or updating dependencies.

Regenerate the lock file

If you need to regenerate the lock file, you can use the following command:

# Example for macos and Python 3.8
pdm lock --python="==3.8.*" --platform=macos --with pyvista --with openpyxl --lockfile=pdm-py38macos.lock
# Example for Windows and Python 3.9+
pdm lock --python="==3.8.*" --platform=windows --with pyvista --with openpyxl --lockfile=pdm-py39+win.lock
# Example for Linux and Python 3.9+
pdm lock --python="==3.8.*" --platform=linux --with pyvista --with openpyxl --lockfile=pdm-py39+unix.lock

Install pre-commit

pdm run pre-commit install --hook-type pre-commit --hook-type pre-push

Run the project

Linux/MAC:

pdm run src/pyoma2/main.py

Updating lock files

To update the lock files for different platforms and Python versions, use the following commands:

For Python 3.8 (Linux/Windows):

pdm lock --python="3.8" --lockfile=pdm-py38.lock

For Python 3.8 (macOS):

pdm lock --python="3.8" --platform=macos --lockfile=pdm-py38macos.lock

For Python 3.9+ (Linux/Windows):

pdm lock --python=">=3.9" --lockfile=pdm-py39+.lock

For Python 3.9+ (macOS):

pdm lock --python=">=3.9" --platform=macos --lockfile=pdm-py39+macos.lock

Make sure to update all relevant lock files when making changes to the project dependencies.

Windows

pdm run .\src\pyoma2\main.py

You'll probably need to install tk for the GUI on your system, here some instructions:

Windows:

https://www.pythonguis.com/installation/install-tkinter-windows/

Linux:

https://www.pythonguis.com/installation/install-tkinter-linux/

Mac:

https://www.pythonguis.com/installation/install-tkinter-mac/

If using python with pyenv:

https://dev.to/xshapira/using-tkinter-with-pyenv-a-simple-two-step-guide-hh5

Building the lock file

Due to NEP 29, Numpy drops support for active versions of Python before their support ends. Therefore, there are versions of numpy that cannot be installed for certain active versions of Python and this leads to PDM unable to resolve the dependencies, or attempting to install a version of numpy that does not have a wheel.

By following Lock for specific platforms or Python versions, you can generate a single lock file for multiple versions of Python with:

pdm lock --python=">=3.9" --with pyvista --with openpyxl
pdm lock --python="==3.8.*" --with pyvista --with openpyxl

When bumping the minimum supported version of Python in pyproject (requires-python), be sure to also bump the conditional numpy versions supported. For example, when Python 3.8 is dropped, you will have to modify:

    "numpy<1.25; python_version < '3.9'",
    "numpy>=1.25; python_version >= '3.9'",

to (this is just a guess; numpy versions will have to change):

    "numpy<2.0; python_version < '3.10'",
    "numpy>=2.0; python_version >= '3.10'",

Running tests

make test

Running tests with coverage

make test-coverage

Running tests with tox on multiple python versions

make tox

Running tests on

Conventions

Commits

Use conventional commits guidelines https://www.conventionalcommits.org/en/v1.0.0/