Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
81 lines (54 loc) · 3.8 KB

CONTRIBUTING.md

File metadata and controls

81 lines (54 loc) · 3.8 KB
Raw

❤️‍🔥 Contributing to this project

Thank you for your interest in contributing to mockbook.

🐛 Reporting issues

Please report issues in our GitHub repository. Before submitting an issue, please search for existing issues to avoid duplicates.

🏗️ Project overview

This project consists of the following components:

  • Python package (mockbook), a FastAPI application serving mock endpoints with live reloading on file changes (/app/mockbook)
  • Preconfigured JupyterLab for writing mock endpoints
  • Preconfigured NGINX reverse proxy for full mocking flexibility
  • NGINX reloader triggered by configuration file changes (/app/mockbook/nginx)

🛠️ Tech stack

This project uses the following tech stack:

  • Python 3.14
  • uv for dependency management and configuration
  • FastAPI for serving mock endpoints
  • JupyterLab for writing mock endpoints
  • NGINX for reverse proxy
  • Supervisor for running services
  • Ruff to format and lint Python code, and Mypy for type checking
  • shfmt and shellcheck for formatting and linting shell scripts, and BATS for running tests

📂 Key directory structure

  • docs/: Documentation resources
  • examples/: Usage examples
  • jupyterlab/: JupyterLab configuration
  • mockbook/: The project's Python package source code
  • mockbook/nginx/: NGINX configuration files
  • scripts/: Shell scripts for running services
  • supervisord/: Supervisor configuration files
  • test/: Project tests
  • docker-compose.yaml: Docker Compose configuration for local development and testing
  • docker-entrypoint.sh: Docker entrypoint script
  • Dockerfile: Docker image definition
  • flake.nix: Nix Flakes development environment
  • Justfile: Commands for development
  • pyproject.toml: Project dependencies and configuration

🔧 Set up the development environment

For development, the following tools are required:

🐳 System requirements

You need Docker and Docker Compose installed on your system.

❄️ Tools managed via Nix Flakes

This repository uses Nix Flakes to manage development tools. The following tools are installed automatically when nix is available:

  • pre-commit
  • just
  • uv
  • nginx

Simply run nix develop to enter the development environment, then run just install to set up dependencies. The Nix shell also installs the pre-commit hooks automatically.

If you prefer using a Dev Container, an example configuration file (devcontainer.json) is provided with Nix and Docker-in-Docker pre-installed.

✅ Verifying changes

Before pushing your code, run just ci to verify that your changes adhere to the project's coding standards and pass all linters, formatters, and tests.

Alternatively, use the pre-commit hooks to handle formatting, linting, type checking, and quick test feedback automatically.

✨ Submitting changes

Please feel free to submit pull requests on GitHub. Before opening a PR, ensure your changes pass all checks by running just ci.

🚀 Release process

The Docker image is published to Docker Hub automatically on pushes to the main branch. To release a new version, create a release in GitHub Releases with a v* tag, which will trigger the publish.yaml workflow to build and push the Docker image with semantic version tags.