Contributing

Contributions to Mariner 2 are welcome! Both code and documentation are hosted on our GitHub repository. If you are not familiar with GitHub and Pull Requests, we recommend for you to read GitHub’s documentation.

This document will guide you through setting up your development environment to develop mariner itself and write documentation.

Before diving into the sections below, make sure you have a checkout of the mariner git repository:

$ git clone https://github.com/amd989/mariner.git

Development

Mariner 2 is developed largely on top of Python, TypeScript and React.

If you are interested to help with development, first make sure that you have Python 3.11 (or newer) installed. We also use Poetry for dependency management, so you should have that installed as well.

If you would like to do frontend development, you should have node.js installed (which includes npm).

Once you have those dependencies installed, you can get your virtual environment setup with all the required Python dependencies with poetry:

$ poetry install

Backend

The mariner backend code is responsible for serving HTTP requests from the frontend and communicating with the printer. It’s the core of everything and written in Python. All of the code is within the mariner directory of the Git repository.

If you would like to run mariner locally, you can do so with the following command:

$ poetry run mariner

Note

Before running mariner locally, you will want to build the frontend’s static resources first. Make sure to follow the instructions from the Frontend section below.

The Pi Zero is a bit too slow for development, so we recommend you to do development from another machine or use a Raspberry Pi 4 on your printer which will help considerably, since those models support OTG.

We use green for running backend tests. It is installed by Poetry along with the development dependencies, so you can simply run the backend tests with this command:

$ poetry run green

In addition to running tests, you will want to make sure your code:

  • Passes all Flake8 checks: poetry run flake8

  • Is auto-formatted with Black: poetry run black --check .

  • Is type-checked with pyre: poetry run pyre

If you are not familiar with Python type-checking it is recommended for you to get familiarized with it first, as the mariner code is strictly typed. PEP 484 offers a good overview of the basic functionality and the typing module documentation is a great resource as well.

Frontend

The mariner frontend code is largely written in TypeScript with React. The UI is built with Tailwind CSS and shadcn/ui components. Data fetching is handled by React Query. We use Vite as the build tool and npm to manage frontend dependencies.

All of the frontend source code lives in the frontend directory. So cd into that directory and install the JS dependencies with:

$ npm install

In order to run mariner locally, you will want to package the frontend code into a static resource that can be served by the backend. Do this with:

$ npm run build

If successful, the built assets will be generated under the dist directory. Now you should be able to run mariner locally with poetry run mariner as described on the Backend section.

For development, you can run the Vite dev server which proxies API requests to the Flask backend:

$ npm run dev

You can run the frontend tests with the following command:

$ npm test

Just like on the backend, we use a few tools to hold the style guidelines and best practices of the codebase. So make sure to do these checks on your code:

  • ESLint issues with: npm run lint

Pre-commit Hooks

We run tests, style and typing checks automatically on all commits and pull requests with a GitHub Action. However, you can also automatically run those locally before every commit you make with pre-commit. See pre-commit’s installation instructions for more information. Once you have pre-commit installed, setup the mariner hook by running this from your local repository:

$ pre-commit install

Once the pre-commit hook is installed, any commits to your local mariner repository will automatically run all backend and frontend checks that would be run on the GitHub Action.

Documentation

All of mariner’s documentation (including this document!) is hosted on the mariner repository itself under the docs/ directory. We use Read the Docs to host our documentation, which is formatted with reStructuredText.

If you would like to make changes to the documentation, you can make those from the GitHub UI itself and submit those as Pull Requests without requiring any local development.

You can also make changes to the documentation and preview them locally. All you need is a local checkout of the mariner repository from GitHub, Python 3.7 (or newer), and Poetry installed. For more information on that setup, refer to the Backend section as the instructions are the same.

To build the documentation locally, just run the following commands:

$ cd docs
$ make html

Then just open docs/_build/html/index.html on your browser.

If you are building the documentation on Windows, there is a make.bat file which you can run instead of make html.