Tooling and library guidelines
- Goals
- Languages
- General Concepts
- APIs
- Python
- Markdown
- Rust
- Shell
- SQL
- Tooling
- Web

Tooling and library guidelines

Goals

Consistency

We want to ensure consistency in the tools and libraries used for the PeopleForBikes projects.

Ideally a contributor working on one project should be familiar enough with the tools and libraries to be able to fix bugs or implement features in another one.

Removing choice fatigue

We aim at preventing choice fatigue by working with tools and libraries that we already battle tested.

For instance a contributor looking to implement some logging in a new project should not spend a day or two researching and evaluating libraries, but should instead refer to this guide to pick the one we recommend.

Limiting dependency proliferation

Limiting the amount of third-party software you rely on reduces the surface of attacks you may be vulnerable to.

Here as an example, are just a couple of impactful events that happen within recent years:

Languages

Like dependencies, we try to reduce the amount of general-purpose programming languages we use for PeopleForBikes projects, therefore we decided to only adopt TypeScript, Rust and Python.

They are respectively used for the following use cases:

General Concepts

These are general concepts that we attempt to abide to in the PeopleForBikes projects.

APIs

Python

Project management

We recommend using just for managing administration tasks, but for more complex scenarios invoke is an acceptable replacement.

Poetry settings

Each project must create a local virtual environment at its root :

poetry config virtualenvs.in-project true --local

pyproject.toml

Describes special sections to add to the pyproject.toml configuration file.

coverage

Leaves some files out the measurements.

[tool.coverage.run]
omit = ["*/__init__.py"]

isort

Enables the compatibility with black while shaping the import as a grid where each import has its own line.

[tool.isort]
profile = "black"
force_grid_wrap = 2

pytest

Removes the warnings, configures the code coverage report and run the doctests with xdoctest.

[tool.pytest.ini_options]
minversion = "6.0"
addopts = "-p no:warnings --cov-report term-missing --cov-report html --xdoctest"

Initialization

To quickly start a project, run the following commands:

export POETRY_PROJECT=my-project
poetry new ${POETRY_PROJECT}
cd ${POETRY_PROJECT}
poetry add -G dev \
  bpython \
  furo\
  isort \
  myst-parser \
  pytest \
  pytest-cov \
  pytest-mock \
  pytest-rerunfailures \
  pytest-socket \
  pytest-xdist \
  ruff \
  Sphinx\
  sphinx-autobuild \
  sphinx-copybutton \
  xdoctest

Libraries

Production

Linting

Docs

Testing

Markdown

Rust

Libraries

Shell

SQL

Tooling

Web

Web projects will be built with Next.js using TypeScript

Custom fonts

PFB uses some custom private fonts that require some setup in order to be used.

First, copy the font files into the public/fonts folder of the web project. The font are available in the Brokenspoke repository.

The folders should look like this:

public
├── fonts
│   ├── Dharma Type - DharmaGothicE-Bold.otf
│   └── Dharma Type - DharmaGothicE-Light.otf

Add the new font-faces to styles/globals.css:

// styles/globals.css

@font-face {
  font-family: "Dharma Gothic E";
  src: url("../public/fonts/Dharma Type - DharmaGothicE-ExBold.otf")
    format("opentype");
}

@font-face {
  font-family: "Dharma Gothic E";
  src: url("../public/fonts/Dharma Type - DharmaGothicE-ExLight.otf")
    format("opentype");
}

Component Collections

Here are the components collection that have been selected by the team:

Helpers