Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
234 lines (166 loc) · 5.27 KB

CONTRIBUTING.md

File metadata and controls

234 lines (166 loc) · 5.27 KB

Contributing 101

Quick start

1. Clone the repo

git clone https://github.com/amosproj/amos2025ws04-robot-visual-perception.git
cd amos2025ws04-robot-visual-perception

If you already cloned it earlier, update before starting work:

git pull

2. Create new branch

git checkout -b feat/<issue-number>-<short-description>

Let's try to follow the convention below:

  • feat for new features
  • docs for docs
  • fix for bugfixes
  • exp for anything experimental

E.g., feat/14-architecture

3. Make changes and commit

git add .
git commit  --signoff -m "A good description of the commit"

All commits must be signed off as per AMOS requirements. You can make Git reject unsigned commits automatically:

cd .git/hooks
nano commit-msg

Paste the following:

#!/bin/sh
if ! grep -q '^Signed-off-by:' "$1"; then
  echo "Commit rejected: missing 'Signed-off-by' line."
  echo "Please use: git commit -s"
  exit 1
fi

Then make it executable:

chmod +x .git/hooks/commit-msg

If several people contributed, add co-authors:

git commit -a -m "Fixed problem
> Co-authored-by: Stefan Buchner <stefan.buchner@fau.de>”
> --signoff

4. Push your branch

git push feat/<issue-number>-<short-description>

5. Open a PR

  • Open a PR from your branch into main
  • Assign yourself
  • Link the related issue
  • Add a good PR description
  • Ensure CI passes

6. Closing a PR

  • Never delete branches

Development setup

Before you can run the project locally, install the required tools:

Prerequisites

Node.js 20 (for frontend)

Recommended: Use nvm to manage Node.js versions:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

cd src/frontend
nvm install  # Installs Node.js 20
nvm use      # Switches to Node.js 20

Alternative (without nvm):

brew install node@20

Python 3.11 (for backend)

The Makefile will automatically install Python 3.11 via uv. You just need uv installed:

uv (Python package manager)

curl -LsSf https://astral.sh/uv/install.sh | sh
# or on macOS
brew install uv

Docker (for containerization)

brew install --cask docker

Quick Start for Windows

For Windows developers, use our automated setup script that handles all prerequisites:

PowerShell -ExecutionPolicy Bypass -File .\start-optibot.ps1

What it does:

  • Checks for administrator privileges
  • Installs Chocolatey (if not present)
  • Installs Git, Python 3.11, Node.js 20+, Make, and uv
  • Runs make dev to install dependencies
  • Starts webcam, analyzer, and frontend services in separate windows
  • Opens browser to http://localhost:3000

Optional parameters:

# Custom camera settings
.\start-optibot.ps1 -CameraIndex 1 -CameraWidth 1920 -CameraHeight 1080 -CameraFPS 60

# Skip the build step (if already built)
.\start-optibot.ps1 -SkipBuild

# Custom backend port
.\start-optibot.ps1 -BackendPort 8080

Note: Administrator rights are required for installing dependencies via Chocolatey.

For manual setup or non-Windows platforms, follow the instructions below.

Development

Install dependencies

After installing the tools above, run:

make dev

This will:

  • Install frontend dependencies (npm packages)
  • Create Python virtual environment and install backend dependencies

Formatting

Format your code before committing to maintain consistent style:

make format                # Format all code (frontend and backend)
make format-frontend       # Format frontend with Prettier
make format-backend        # Format backend with Ruff

Running linters

Linting catches code issues and enforces style guidelines. Always run before pushing:

make lint                  # Lint all components (includes type checking)
make lint-frontend         # Lint frontend with ESLint
make lint-backend          # Lints and type checks backend with Ruff

Before you push your changes, run make lint and address any errors.

Running tests

make test                  # Run all tests (frontend and backend)
make test-frontend         # Run frontend tests with Vitest
make test-backend          # Run backend tests with pytest

Docker commands

Build Docker images (used in CI):

make docker-build          # Build all Docker images
make docker-build-frontend # Build frontend image
make docker-build-backend  # Build backend image

Run all services with Docker Compose (Linux only):

make docker-compose-up     # Start all services (webcam, analyzer, frontend)
make docker-compose-down   # Stop all services

Important: Camera device access (/dev/video0) only works on Linux. Docker Desktop on macOS/Windows cannot access hardware devices. For non-Linux systems, run services locally instead.

Generating the Bill of Material (BOM)

To generate the Bill of Material (BOM) for the current sprint, run:

make sbom

This will list the first level dependencies inside sbom-dependencies.csv.

You can also look into the latest GitHub Action run which will have the current SBOM published as artifact.