Contributing
Contributions to mariner 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/luizribeiro/mariner.git
Development
Mariner 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.7 (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 and the yarn package manager.
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 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. Most of the frontend is built with Material-UI components. HTTP requests are made to the backend API endpoints with Axios. We use yarn to manage our frontend dependencies, so make sure to have that installed before you move forward.
All of the frontend source code lives in the frontend
directory. So cd
into that directory and install the JS dependencies with:
$ yarn 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:
$ yarn build
If successful, a main.js
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.
You can run the frontend tests with the following command:
$ yarn --cwd frontend 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:
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
.