Contributing

There are a few ways to contribute:

  • Raise an issue to identify a bug or suggest a new feature.

  • Fork the repository and make a pull request to suggest changes to the code.

  • If you’d like to contribute a mass database, please do this by raising an issue.

Repository Structure

Currently, the pgfinder repository is split into two major parts: in the lib folder is the library (and CLI) code that forms the heart of PGFinder. The code in this directory is written purely in Python. The other half of this repository is the pgfinder-gui web application — this code lives in the web directory. This webapp is written using SvelteKit and simply wraps PGFinder into a presentable package and passes user inputs to the pgfinder Python package (running in the client’s browser via WebAssembly / Pyodide).

As these two halves of the applicaton are written using different languages and frameworks, you’ll need different tools to contribute to each of them.

Hacking On The lib Directory

Development Installation

The current version when installed from GitHub is a combination of the most recent Git tag combined with the hash of the current HEAD of the branch and how many commits away from the last tag it is.

If you wish to contribute to the development of PGFinder, you should clone (your fork of) this repository, navigate to the lib directory, and install pgfinder in editable mode (pip install -e) with the following commands (which install additional dependencies for tests, documentation and linting).

# Clone the repository
git clone https://github.com/Mesnage-Org/PGFinder.git
cd pgfinder/lib
# Install in editable mode
pip install -e .
# Install extra dependencies
pip install -e ".[dev,docs,tests]"

Testing

To run unit tests suite use pytest

# From the `lib` directory...
pytest

Linting (Also Used in web)

PGFinder uses pre-commit hooks to ensure code conforms to the PEP8 Python Style Guide using the ruff linter, applies black formatting, and checks for a number of other common mistakes. These hooks are run on GitHub when Pull Requests are made using pre-commit.ci, and if you have not run them locally, then your pull request may fail the tests it needs to pass.

pre-commit will have been installed as part of the extra dependencies above (they are part of dev), but you need to install pre-commit and the hooks locally in your virtual environment. This can be done with the following commands.

pre-commit install
pre-commit install-hooks

Now when you make a git commit, the hooks will run first and report any errors. If the errors can be corrected automatically, they will be, but you will have to then git stage the modified files again before completing the commit (this gives you an opportunity to review the changes that have been made, but typically they are ok to accept — they will be black formatting or other trivial code-style changes).

Releasing to PyPI

Releases to the Python Package Index (PyPI) are automated and occur when a new release is made on GitHub with a tag that begins with v#.#.#'. PGFinder uses semantic verisoning.

Hacking On The web Directory

Development Installation

To contribute to the PGFinder web interface, we recommend using pnpm. After navigating to the web directory, it’s easy to get a development version of the GUI running using the commands defined in package.json.

# From the `web` directory...
cd web/
# Install all development dependencies
pnpm install
# Spin up a development version of the GUI
pnpm dev

The development server is equipped with hot-reloading, so there is no need to restart it as you make changes. After making a change and saving the file you were working on, the webpage should reload automatically.

Testing

To test the GUI’s functionality (and that it’s correctly interfacing with the pgfinder backend), you can run pnpm test, which leverages Playwright for end-to-end testing.

# Start browser testing in the background
pnpm test
# Start an interactive testing session and open the UI
pnpm test -- --ui

Formatting

To ensure consistent formating throughout the web directory, you can run Prettier using the following command:

# Run Prettier
pnpm format

Linting

To check for errors or potential improvements to code style, you can run the following commands:

# Check for hard-errors (svelte-check)
pnpm check
# Do the same, but automatically recheck when the code is changed
pnpm check:watch
# Check for potential improvements to code style
pnpm lint